Expenses#

Read manual expenses and provider-reported advertising spend together, with explicit provenance and aggregate spend reporting across Activities.

Authentication required

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

GET /v1/expenses#

List manual expense records and read-only provider-reported advertising spend across Activities. Provenance distinguishes editable expenses from retained platform measurements. Sort the combined ledger before pagination.

bash

GET /v1/expenses?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).
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.
activityId	`string (UUID)`	—	Filter by activity identifier.
creatorId	`string (UUID)`	—	Filter by creator identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.
searchTerm	`string`	—	Search expense category, description, or activity name.
categoryId	`string (UUID)`	—	Filter by expense category identifier.
sortBy	`'amount' \| 'createdAt'`	—	Expense field to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.

Response#

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

GET /v1/expenses/count#

Count the manual expense and provider-reported spend records shown in the Spend ledger, with optional Activity, creator, or Campaign filters.

bash

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
activityId	`string (UUID)`	—	Filter by activity identifier.
creatorId	`string (UUID)`	—	Filter by creator identifier.
campaignId	`string (UUID)`	—	Filter by campaign identifier.

Response#

Returns { count, _meta }.

GET /v1/expenses/stats#

Aggregate total spend, spend coverage, non-campaign spend, and largest category using the active spend filters.

bash

GET /v1/expenses/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.
activityId	`string (UUID)`	—	Unique identifier (UUID v4).
creatorId	`string (UUID)`	—	Unique identifier (UUID v4).
campaignId	`string (UUID)`	—	Unique identifier (UUID v4).
searchTerm	`string`	—
categoryId	`string (UUID)`	—	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.

GET /v1/expenses/history#

Fetch daily recorded marketing spend and a running cumulative total for a date range. Each spend is attributed to the day its activity ran (publish date for social content, start date for other channels) and days without spend are zero-filled, so budget and spend read alongside traffic and brand signals on one timeline.

bash

GET /v1/expenses/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

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