Activities#

Track delivered marketing activity across social, broadcast, out-of-home, print, events, podcasts, and PR.

Authentication required

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

GET /v1/activities#

Retrieve a paginated list of activities for a workspace, filterable by campaign, creator, channel, status, date range, and whether impression metrics are available or missing.

bash

GET /v1/activities?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' \| 'startAt' \| 'impressions' \| 'engagement' \| 'spend' \| 'cpe' \| 'cpm' \| 'createdAt'`	—	Activity 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.
metricsAvailability	`'available' \| 'missing'`	—	Filter by impression data availability. Available includes measured zero; missing means no impression value is recorded.
channelType	`'social_media' \| 'paid_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles' \| 'listings' \| 'guest_content' \| 'partnerships' \| 'other'`	—	Filter by channel group.
channelTypes	`Array<'social_media' \| 'paid_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles' \| 'listings' \| 'guest_content' \| 'partnerships' \| 'other'>`	—	Filter by one or more channel groups.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'google_ads' \| 'meta_ads' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'online_event' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article' \| 'directory' \| 'review_site' \| 'app_marketplace' \| 'launch_site' \| 'guest_post' \| 'arranged_mention' \| 'co_marketing' \| 'referral_program' \| 'other_activity'	—	Filter by specific channel.
channels	Array<'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'google_ads' \| 'meta_ads' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'online_event' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article' \| 'directory' \| 'review_site' \| 'app_marketplace' \| 'launch_site' \| 'guest_post' \| 'arranged_mention' \| 'co_marketing' \| 'referral_program' \| 'other_activity'>	—	Filter by one or more specific channels.
creatorId	`string (UUID)`	—	Filter by creator identifier.
postedBy	`'own_brand' \| 'others'`	—	own_brand: only what your brand posted on its own accounts. others: everything else, such as creator posts and paid media.
mediaProviderId	`string (UUID)`	—	Filter by media provider identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.
unlinkedFromCampaign	`boolean`	—	Exclude campaign-linked activities.
unlinkedFromCreatorId	`string (UUID)`	—	Exclude links to this creator.

Response#

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

GET /v1/activities/count#

Get the total number of activities matching the given filters, including whether impression metrics are available or missing.

bash

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
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.
metricsAvailability	`'available' \| 'missing'`	—	Filter by impression data availability. Available includes measured zero; missing means no impression value is recorded.
channelType	`'social_media' \| 'paid_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles' \| 'listings' \| 'guest_content' \| 'partnerships' \| 'other'`	—	Filter by channel group.
channelTypes	`Array<'social_media' \| 'paid_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles' \| 'listings' \| 'guest_content' \| 'partnerships' \| 'other'>`	—	Filter by one or more channel groups.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'google_ads' \| 'meta_ads' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'online_event' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article' \| 'directory' \| 'review_site' \| 'app_marketplace' \| 'launch_site' \| 'guest_post' \| 'arranged_mention' \| 'co_marketing' \| 'referral_program' \| 'other_activity'	—	Filter by specific channel.
channels	Array<'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'google_ads' \| 'meta_ads' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'online_event' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article' \| 'directory' \| 'review_site' \| 'app_marketplace' \| 'launch_site' \| 'guest_post' \| 'arranged_mention' \| 'co_marketing' \| 'referral_program' \| 'other_activity'>	—	Filter by one or more specific channels.
creatorId	`string (UUID)`	—	Filter by creator identifier.
postedBy	`'own_brand' \| 'others'`	—	own_brand: only what your brand posted on its own accounts. others: everything else, such as creator posts and paid media.
mediaProviderId	`string (UUID)`	—	Filter by media provider identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.

Response#

Returns { count, _meta }.

GET /v1/activities/stats#

Aggregate statistics for activities matching the given filters, including whether impression metrics are available or missing, optionally including spend and impression totals grouped by channel.

bash

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
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.
metricsAvailability	`'available' \| 'missing'`	—	Filter by impression data availability. Available includes measured zero; missing means no impression value is recorded.
channelType	`'social_media' \| 'paid_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles' \| 'listings' \| 'guest_content' \| 'partnerships' \| 'other'`	—	Filter by channel group.
channelTypes	`Array<'social_media' \| 'paid_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles' \| 'listings' \| 'guest_content' \| 'partnerships' \| 'other'>`	—	Filter by one or more channel groups.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'google_ads' \| 'meta_ads' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'online_event' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article' \| 'directory' \| 'review_site' \| 'app_marketplace' \| 'launch_site' \| 'guest_post' \| 'arranged_mention' \| 'co_marketing' \| 'referral_program' \| 'other_activity'	—	Filter by specific channel.
channels	Array<'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'google_ads' \| 'meta_ads' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'online_event' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article' \| 'directory' \| 'review_site' \| 'app_marketplace' \| 'launch_site' \| 'guest_post' \| 'arranged_mention' \| 'co_marketing' \| 'referral_program' \| 'other_activity'>	—	Filter by one or more specific channels.
creatorId	`string (UUID)`	—	Filter by creator identifier.
postedBy	`'own_brand' \| 'others'`	—	own_brand: only what your brand posted on its own accounts. others: everything else, such as creator posts and paid media.
mediaProviderId	`string (UUID)`	—	Filter by media provider identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.
includeChannels	`boolean`	—	Include full, unpaginated spend and impression aggregates grouped by channel.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).

Response#

Returns { data, _meta } with the result.

POST /v1/activities#

Create social or provider-delivered activity with channel-specific delivery details, metrics, an initial spend or expense line, and the person or company that delivered it. Social media activity is delivered by a creator; broadcast, out-of-home, print, event, podcast, and PR activity is delivered by a media provider.

bash

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

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
channelType	`'social_media' \| 'paid_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles' \| 'listings' \| 'guest_content' \| 'partnerships' \| 'other'`	—	Top-level channel group for this activity. Defaults to social_media, where a creator posts the content. Every other group is delivered by a media provider.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'google_ads' \| 'meta_ads' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'online_event' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article' \| 'directory' \| 'review_site' \| 'app_marketplace' \| 'launch_site' \| 'guest_post' \| 'arranged_mention' \| 'co_marketing' \| 'referral_program' \| 'other_activity'	Required	Specific activity channel or subtype.
activity	`'instagram_story' \| 'instagram_post' \| 'instagram_reel' \| 'youtube_video' \| 'youtube_short' \| 'tiktok_video' \| 'twitter_post' \| 'linkedin_post' \| 'reddit_post' \| 'google_ad' \| 'google_asset_group' \| 'google_ad_group' \| 'google_campaign' \| 'meta_ad' \| null`	—
job	`'build' \| 'findable' \| 'convert' \| null`	—	The job this activity does, as confirmed by the user. Leave it out to keep the job Brandwave suggests from the activity type until someone confirms it. Other has no suggestion, so set it there.
name	`string`	Required	Activity name or title (max 500 characters).
startAt	`string (ISO 8601) \| null \| null`	—
endAt	`string (ISO 8601) \| null \| null`	—
creatorId	`string (UUID)`	—	Creator who delivered the activity. Social media activities only.
mediaProviderId	`string (UUID) \| null`	—	Media provider that delivered the placement. Required for provider-delivered activity; social media activities cannot be linked to a media provider.
impressions	`integer \| null`	—	Delivered or estimated impression count.
deliverySource	`'platform_reported' \| 'provider_reported' \| 'user_entered' \| 'benchmark_estimated' \| 'modeled' \| null`	—	Provenance of the delivered activity metrics.
deliverySourceMetadata	`object \| null`	—	Structured provenance metadata for delivered activity metrics.
initialExpense	`object`	—	Optional initial expense line item to create with the activity.
broadcastDetails	`object`	—	Broadcast placement and delivery details.
outOfHomeDetails	`object`	—	Out-of-home placement and delivery details.
printDetails	`object`	—	Print placement and delivery details.
eventDetails	`object`	—	Event participation and delivery details.
podcastDetails	`object`	—	Podcast placement and delivery details.
prArticleDetails	`object`	—	PR article placement and delivery details.

Response#

Returns { data, _meta } with the result.

PATCH /v1/activities/:id#

Update an activity's channel, content link, metrics, media provider, or channel-specific delivery details.

bash

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

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Activity identifier to update.
channelType	`'social_media' \| 'paid_media' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'events' \| 'podcasts' \| 'pr_articles' \| 'listings' \| 'guest_content' \| 'partnerships' \| 'other'`	—	Top-level channel group for this activity. listings covers directories, review sites, app stores and launch sites; guest_content covers guest posts and mentions you arranged; partnerships covers co-marketing and referral or affiliate programmes; other is anything else.
channel	'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit' \| 'google_ads' \| 'meta_ads' \| 'radio' \| 'television' \| 'billboard' \| 'bus_shelter' \| 'street_furniture' \| 'digital_outdoor_screen' \| 'transit_ad' \| 'newspaper' \| 'magazine' \| 'flyer' \| 'conference' \| 'trade_show' \| 'expo' \| 'networking_event' \| 'community_event' \| 'festival' \| 'online_event' \| 'other_event' \| 'podcast_interview' \| 'podcast_guest_segment' \| 'podcast_sponsored_segment' \| 'other_podcast' \| 'online_pr_article' \| 'print_pr_article' \| 'syndicated_pr_article' \| 'other_pr_article' \| 'directory' \| 'review_site' \| 'app_marketplace' \| 'launch_site' \| 'guest_post' \| 'arranged_mention' \| 'co_marketing' \| 'referral_program' \| 'other_activity'	—	Updated channel.
activity	`'instagram_story' \| 'instagram_post' \| 'instagram_reel' \| 'youtube_video' \| 'youtube_short' \| 'tiktok_video' \| 'twitter_post' \| 'linkedin_post' \| 'reddit_post' \| 'google_ad' \| 'google_asset_group' \| 'google_ad_group' \| 'google_campaign' \| 'meta_ad' \| null`	—	Updated content type.
job	`'build' \| 'findable' \| 'convert' \| null`	—	Confirm or change the job this activity does. Null goes back to the unconfirmed suggestion.
name	`string`	—	Updated activity name (max 500 characters).
startAt	`string (ISO 8601) \| null \| null`	—	Updated start date.
endAt	`string (ISO 8601) \| null \| null`	—	Updated end date.
mediaProviderId	`string (UUID) \| null`	—	Updated provider for a provider-delivered activity.
impressions	`integer \| null`	—	Updated delivered or estimated impression count.
deliverySource	`'platform_reported' \| 'provider_reported' \| 'user_entered' \| 'benchmark_estimated' \| 'modeled' \| null`	—	Updated provenance of the delivered activity metrics.
broadcastDetails	`object`	—	Updated broadcast delivery details.
outOfHomeDetails	`object`	—	Updated out-of-home delivery details.
printDetails	`object`	—	Updated print delivery details.
eventDetails	`object`	—	Updated event delivery details.
podcastDetails	`object`	—	Updated podcast delivery details.
prArticleDetails	`object`	—	Updated PR article delivery details.
contentHref	`string (URL) \| null`	—	URL to the original content (max 2,048 characters).
viewsCount	`integer \| null`	—	Manual view count override (non-negative integer).
likeCount	`integer \| null`	—	Manual like count override (non-negative integer).
replyCount	`integer \| null`	—	Manual reply count override (non-negative integer).

Response#

Returns { data, _meta } with the result.

Content link changes reset metrics

Changing the contentLink triggers a metric refresh. Previous metric snapshots are preserved but the latest values will update.

DELETE /v1/activities/:id#

Permanently delete an activity and its associated records.

bash

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

Parameters#

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

Response#

Returns { data, _meta } with the result.

Destructive action

Deleting an activity permanently removes all linked metrics, expenses, creator associations, and notes. This action cannot be undone.

POST /v1/activities/content-link/connect#

Connect a social media post URL to an activity for automatic metric tracking.

bash

POST /v1/activities/content-link/connect
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02",
  "platform": "instagram",
  "content_url": "..."
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to connect the content link to.
platform	`'instagram' \| 'youtube' \| 'tiktok' \| 'twitter' \| 'linkedin' \| 'reddit'`	Required	Social media platform for this content.
contentUrl	`string`	Required	URL to the social media content (max 2,048 characters).

Response#

Returns { data, _meta } with the result.

Metric refresh

Connecting a content link triggers an immediate metric fetch for the linked post.

POST /v1/activities/content-link/disconnect#

Disconnect a content link from an activity, stopping automatic metric tracking.

bash

POST /v1/activities/content-link/disconnect
Authorization: Bearer {token}
Content-Type: application/json

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to disconnect the content link from.

Response#

Returns { data, _meta } with the result.

GET /v1/activities/creators#

List creators linked to an activity with pagination.

bash

GET /v1/activities/creators?page_index=0&page_size=25&workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
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.
activityId	`string (UUID)`	Required	Activity identifier to list creators for.

Response#

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

GET /v1/activities/creators/count#

Count the number of creators linked to an activity.

bash

GET /v1/activities/creators/count?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
activityId	`string (UUID)`	Required	Activity identifier to count creators for.

Response#

Returns { count, _meta }.

POST /v1/activities/:id/creators#

Associate a creator with an activity.

bash

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

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02",
  "creator_id": "9b4c2e78-1a53-4f6d-b8e9-0c7a5d3f1e04"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to link.
creatorId	`string (UUID)`	Required	Creator identifier to link.

Response#

Returns { data, _meta } with the result.

DELETE /v1/activities/:id/creators/:creatorId#

Remove a creator association from an activity.

bash

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

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02"
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to unlink from.
creatorId	`string (UUID)`	Required	Creator identifier to unlink.

Response#

Returns { data, _meta } with the result.

Cascading deletion

Unlinking a creator removes all expense records associated with that creator on this activity.

POST /v1/activities/expenses#

Add a expense line item with net amount, currency, category, creator attribution, tax breakdown, and booking reference.

bash

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

{
  "activity_id": "7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02",
  "amount": "150.00",
  "category_id": "...",
  "currency": "..."
}

Parameters#

Name	Type	Required	Description
activityId	`string (UUID)`	Required	Activity identifier to add the expense to.
amount	`number`	Required	Expense amount (must be greater than zero, max 100M).
categoryId	`string (UUID)`	Required	Reusable expense category identifier.
currency	`string`	Required	ISO 4217 currency code, e.g. "USD", "NZD" (exactly 3 characters).
description	`string \| null`	—	Optional description of this expense line item (max 1,000 characters).
creatorId	`string (UUID) \| null`	—	Creator this expense is attributed to.
grossAmount	`number \| null`	—	Gross booked spend before discounts and tax adjustments.
discountAmount	`number \| null`	—	Discount applied to the gross booked spend.
taxAmount	`number \| null`	—	Tax amount recorded for the spend.
bookingReference	`string \| null`	—	Provider booking or insertion-order reference.

Response#

Returns { data, _meta } with the result.

Auto-linking

If the activity has exactly one linked creator, the spend is automatically attributed to that creator.

PATCH /v1/activities/expenses/:id#

Update a expense line item's net, gross, discount, and tax amounts, category, creator attribution, description, or booking reference.

bash

PATCH /v1/activities/expenses/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Expense record identifier to update.
amount	`number`	—	Updated expense amount (must be greater than zero, max 100M).
categoryId	`string (UUID)`	—	Updated reusable expense category identifier.
description	`string \| null`	—	Updated description (max 1,000 characters).
creatorId	`string (UUID) \| null`	—	Updated creator attribution.
grossAmount	`number \| null`	—	Gross booked spend before discounts and tax adjustments.
discountAmount	`number \| null`	—	Discount applied to the gross booked spend.
taxAmount	`number \| null`	—	Tax amount recorded for the spend.
bookingReference	`string \| null`	—	Provider booking or insertion-order reference.

Response#

Returns { data, _meta } with the result.

DELETE /v1/activities/expenses/:id#

Remove a expense line item from an activity.

bash

DELETE /v1/activities/expenses/:id
Authorization: Bearer {token}

Parameters#

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

Response#

Returns { data, _meta } with the result.

GET /v1/activities/:id#

Retrieve a single activity by ID with full details.

bash

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

Parameters#

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

Response#

Returns { data, _meta } with the result.

GET /v1/activities/metrics/confidence#

Assess the statistical confidence of an activity's metrics.

bash

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`unknown`	—	Start date for confidence calculation window.
endDate	`unknown`	—	End date for confidence calculation window.

Response#

Returns { data, _meta } with the result.

GET /v1/activities/sparklines#

Fetch sparkline chart data for one or more activities.

bash

GET /v1/activities/sparklines?activity_ids=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
activityIds	`Array<string (UUID)>`	Required	Array of activity identifiers to fetch sparkline data for.

Response#

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

GET /v1/activities/metrics#

Fetch metrics for a single activity including impressions, engagement, spend, CPM, and CPE.

bash

GET /v1/activities/metrics?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

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

Response#

Returns { data, _meta } with the result.

GET /v1/activities/launch-response#

Retrieve what was happening around the time one activity went live: other activities that started in the same days, and where it sits among work of the same channel and type that year. For Convert work it also compares brand searches, sessions, results, and customers naming your marketing in the three days after launch with a usual day from the four weeks before, plus visits through promo codes and tagged links mapped to the activity. Build work returns the long_view state without that reading, because its effect shows over months. It reports timing and does not assign attribution.

bash

GET /v1/activities/launch-response?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
activityId	`string (UUID)`	Required	Activity whose launch to read.

Response#

Returns { data, _meta } with the result.

GET /v1/activities/metrics/history#

Fetch an activity's metrics over time with a configurable lookback window.

bash

GET /v1/activities/metrics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

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

Response#

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