Campaigns#

Group activities into campaigns for aggregate reporting.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/campaigns#

Retrieve a paginated list of campaigns for a workspace, ordered by name, dates, budget, or totals.

bash

GET /v1/campaigns?page_index=0&page_size=25&workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
workspaceId	`string (UUID)`	Required	Workspace identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).
sortBy	`'name' \| 'createdAt' \| 'startAt' \| 'endAt' \| 'budget' \| 'activitiesCount' \| 'engagement' \| 'impressions' \| 'spend' \| 'cpe' \| 'cpm'`	—	Campaign field to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.
dateFrom	`string`	—	Earliest date to include, as YYYY-MM-DD in the workspace timezone.
dateTo	`string`	—	Latest date to include, as YYYY-MM-DD in the workspace timezone. Use the same date as dateFrom for a single day.
status	`'active' \| 'scheduled' \| 'completed' \| 'draft'`	—	Filter by campaign status.
kind	`'campaign' \| 'always_on'`	—	Filter to dated campaigns or always-on work.
creatorId	`string (UUID)`	—	Filter by creator identifier.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/campaigns/stats#

Aggregate statistics for campaigns matching the given filters.

bash

GET /v1/campaigns/stats?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
dateFrom	`string`	—	Earliest date to include, as YYYY-MM-DD in the workspace timezone.
dateTo	`string`	—	Latest date to include, as YYYY-MM-DD in the workspace timezone. Use the same date as dateFrom for a single day.
workspaceId	`string (UUID)`	Required	Workspace identifier.
status	`'active' \| 'scheduled' \| 'completed' \| 'draft'`	—	Filter by campaign status.
kind	`'campaign' \| 'always_on'`	—	Filter to dated campaigns or always-on work.
creatorId	`string (UUID)`	—	Filter by creator identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).

Response#

Returns { data, _meta } with the result.

GET /v1/campaigns/:id#

Retrieve a single campaign by ID with full details.

bash

GET /v1/campaigns/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Campaign identifier.

Response#

Returns { data, _meta } with the result.

POST /v1/campaigns#

Create a campaign planning record with a name, summary, objective, audience, key message, desired outcomes, planned channels, owner, tags, dates, and budget. Status is derived from its dates and the response includes a mutation receipt.

bash

POST /v1/campaigns
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "name": "My Campaign"
}

Parameters#

Name	Type	Required	Description
summary	`string \| null`	—	Short internal campaign summary.
objective	`string \| null`	—	Business or marketing objective the campaign is intended to advance.
audience	`string \| null`	—	Intended audience for the campaign.
keyMessage	`string \| null`	—	Primary message the campaign should communicate.
desiredOutcomes	`string \| null`	—	Desired outcomes or KPIs, without implying causal attribution.
channels	`Array<string>`	—	Planned channel labels for the campaign.
ownerUserId	`string (UUID) \| null`	—	Workspace user responsible for the campaign.
tags	`Array<string>`	—	Searchable campaign labels.
workspaceId	`string (UUID)`	Required	Workspace identifier.
name	`string`	Required	Campaign name.
kind	`'campaign' \| 'always_on'`	—	campaign (the default) for a dated push; always_on for ongoing work with no end date or budget. Always-on work starts today unless startAt is given.
startAt	`string (ISO 8601) \| null`	—	Campaign start date.
endAt	`string (ISO 8601) \| null`	—	Campaign end date. Leave out for always-on work.
budget	`number \| null`	—	Total campaign budget (non-negative, max 1B). Leave out for always-on work.

Response#

Returns { data, mutation, _meta } with the result and a customer-facing mutation receipt.

PATCH /v1/campaigns/:id#

Update a campaign's planning brief, desired outcomes, owner, tags, budget, or dates. Status is derived from its dates and the response identifies the changed fields.

bash

PATCH /v1/campaigns/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
summary	`string \| null`	—	Short internal campaign summary.
objective	`string \| null`	—	Business or marketing objective the campaign is intended to advance.
audience	`string \| null`	—	Intended audience for the campaign.
keyMessage	`string \| null`	—	Primary message the campaign should communicate.
desiredOutcomes	`string \| null`	—	Desired outcomes or KPIs, without implying causal attribution.
channels	`Array<string>`	—	Planned channel labels for the campaign.
ownerUserId	`string (UUID) \| null`	—	Workspace user responsible for the campaign.
tags	`Array<string>`	—	Searchable campaign labels.
id	`string (UUID)`	Required	Campaign identifier to update.
name	`string`	—	Updated campaign name (1-255 characters).
kind	`'campaign' \| 'always_on'`	—	Switch between a dated campaign and always-on work. Switching to always_on clears the end date and budget.
startAt	`string (ISO 8601) \| null`	—	Updated start date.
endAt	`string (ISO 8601) \| null`	—	Updated end date.
budget	`number \| null`	—	Updated budget (non-negative, max 1B).

Response#

Returns { data, mutation, _meta } with the result and a customer-facing mutation receipt.

DELETE /v1/campaigns/:id#

Remove a campaign from normal use and unlink its associated activities. The response includes a customer-facing deletion receipt.

bash

DELETE /v1/campaigns/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Campaign identifier to delete.

Response#

Returns { data, mutation, _meta } with the result and a customer-facing mutation receipt.

Destructive action

Deleting a campaign permanently removes the campaign and unlinks all associated activities. This action cannot be undone.

POST /v1/campaigns/preview#

Retrieve a no-write preview of the exact customer-facing target, desired outcomes, budget, changed fields, derived status, and warning for a campaign create, update, delete, or duplicate action.

bash

POST /v1/campaigns/preview
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "operation": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
operation	`'create' \| 'update' \| 'delete' \| 'duplicate'`	Required	Campaign action to preview without changing data.
id	`string (UUID)`	—	Existing campaign identifier for update, delete, or duplicate.
name	`string`	—	Campaign name for create, update, or duplicate.
startAt	`string (ISO 8601) \| null`	—	Proposed campaign start date.
endAt	`string (ISO 8601) \| null`	—	Proposed campaign end date.
budget	`number \| null`	—
summary	`string \| null`	—	Short internal campaign summary.
objective	`string \| null`	—	Business or marketing objective the campaign is intended to advance.
audience	`string \| null`	—	Intended audience for the campaign.
keyMessage	`string \| null`	—	Primary message the campaign should communicate.
desiredOutcomes	`string \| null`	—	Desired outcomes or KPIs, without implying causal attribution.
channels	`Array<string>`	—	Planned channel labels for the campaign.
ownerUserId	`string (UUID) \| null`	—	Workspace user responsible for the campaign.
tags	`Array<string>`	—	Searchable campaign labels.

Response#

Returns { data, _meta } with the result.

POST /v1/campaigns/:id/duplicate#

Create a new draft by duplicating a campaign planning brief, optionally replacing its name and dates. Activities are not copied because an activity belongs to one campaign at a time.

bash

POST /v1/campaigns/:id/duplicate
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Campaign identifier to duplicate.
name	`string`	—	Name for the duplicated campaign.
startAt	`string (ISO 8601) \| null`	—	Optional replacement start date.
endAt	`string (ISO 8601) \| null`	—	Optional replacement end date.

Response#

Returns { data, mutation, _meta } with the result and a customer-facing mutation receipt.

POST /v1/campaigns/:id/activities#

Link an activity to a campaign.

bash

POST /v1/campaigns/:id/activities
Authorization: Bearer {token}
Content-Type: application/json

{
  "campaign_id": "3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03",
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02"
}

Parameters#

Name	Type	Required	Description
campaignId	`string (UUID)`	Required	Campaign identifier to link the activity to.
activityId	`string (UUID)`	Required	Activity identifier to link.

Response#

Returns { data, _meta } with the result.

DELETE /v1/campaigns/:id/activities/:activityId#

Unlink an activity from a campaign.

bash

DELETE /v1/campaigns/:id/activities/:activityId
Authorization: Bearer {token}
Content-Type: application/json

{
  "campaign_id": "3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03"
}

Parameters#

Name	Type	Required	Description
campaignId	`string (UUID)`	Required	Campaign identifier.
activityId	`string (UUID)`	Required	Activity identifier to unlink.

Response#

Returns { data, _meta } with the result.

GET /v1/campaigns/metrics#

Fetch metrics for a single campaign including ISO currency, budget, spend, impressions, social engagement, delivery coverage, denominator-aware CPM and Social CPE, freshness, provenance, and data-quality warnings.

bash

GET /v1/campaigns/metrics?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Campaign identifier to get metrics for.

Response#

Returns { data, _meta } with the result.

GET /v1/campaigns/metrics/history#

Fetch campaign metrics over time with a configurable lookback window.

bash

GET /v1/campaigns/metrics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Campaign identifier.
daysBack	`integer`	—	Number of days of history to return (1-365).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/campaigns/portfolio#

Retrieve decision-ready portfolio health as the preferred starting point for broad campaign-health questions, including active, scheduled, completed, draft, and attention counts; budget and spend totals; brief completeness; evidence quality; priorities; and recommended next actions.

bash

GET /v1/campaigns/portfolio?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&days_back=30
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
daysBack	`integer`	Required	Trailing window used for campaign changes and portfolio findings (1-365).

Response#

Returns { data, _meta } with the result.

GET /v1/campaigns/comparison#

Retrieve the preferred comparison workflow for selected campaigns over a trailing period, including current values, historical changes, denominator-aware efficiency metrics, ISO currency, evidence quality, and plain-language findings.

bash

GET /v1/campaigns/comparison?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_ids=...&days_back=30
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignIds	`Array<string (UUID)>`	Required	Campaign identifiers to compare.
daysBack	`integer`	Required	Trailing comparison window (1-365 days).

Response#

Returns { data, _meta } with the result.

GET /v1/campaigns/readiness#

Assess whether a campaign is ready to launch by reviewing its summary, objective, audience, desired outcomes, planned channels, dates, owner, budget, and linked activities.

bash

GET /v1/campaigns/readiness?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Campaign identifier to assess before launch.

Response#

Returns { data, _meta } with the result.

GET /v1/campaigns/closeout#

Generate a campaign closeout or review with recorded performance, ISO currency, evidence quality, limitations, and recommended follow-up actions without claiming causal attribution.

bash

GET /v1/campaigns/closeout?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Campaign identifier to summarize for closeout or review.

Response#

Returns { data, _meta } with the result.