Costs#

Read-only access to cost records and aggregate cost reporting across activities.

Authentication required

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

GET /v1/costs#

List cost records across activities, including creator details, with global amount or creation-date sorting before pagination.

bash

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

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
organizationId	`string (UUID)`	Required	Organization 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 cost category, description, or activity name.
categoryId	`string (UUID)`	—	Filter by cost category identifier.
sortBy	`'amount' \| 'createdAt'`	—	Cost field to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.

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

Count cost records with optional activity and creator filters.

bash

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

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

Returns { count, _meta }.

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

bash

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

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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).

Returns { data, _meta } with the result.