Listing Usage Records

Individual usage records capture granular token and resource consumption events throughout your application. Each record corresponds to a specific operation - such as a conversation completion, a task execution, or an ability invocation - and includes the type of usage, the count of units consumed, and links to the related platform resources.

Listing usage records gives you detailed, audit-level visibility into how your application consumes platform resources. Unlike the aggregate usage fetch endpoint, this endpoint returns individual event records that can be filtered, paginated, and correlated with specific conversations, bots, tasks, and other platform entities.

GET /api/v1/usage/list
http

Pagination

Results are returned in pages using cursor-based pagination. Include the cursor value from a previous response to fetch the next page. Use the order parameter to control sort direction (asc or desc, defaulting to desc for most recent records first), and the take parameter to control page size.

GET /api/v1/usage/list?take=50&order=desc
http

Filtering by Resource

You can narrow results to usage records associated with a specific platform resource by providing one of the available filter parameters. This is particularly useful when auditing consumption for a particular bot, conversation, or task.

GET /api/v1/usage/list?botId=bot_abc123
GET /api/v1/usage/list?conversationId=conv_xyz789
GET /api/v1/usage/list?type=conversation%2Fcomplete
http

Supported filter fields include type, conversationId, messageId, taskId, contactId, blueprintId, botId, datasetId, skillsetId, and abilityId. Multiple filters can be combined to narrow results further.

Filtering by Metadata

Usage records can also be filtered using metadata key-value pairs attached at the time of recording. Use the meta query parameter with deep object syntax to match records by their metadata values.

GET /api/v1/usage/list?meta[reason]=conversation%2Fcomplete
http

Response Structure

Each record in the items array includes the usage type (a string identifying the operation category), a count representing the number of units consumed (such as token count), optional relation IDs linking the record to platform resources, custom meta data, and standard createdAt and updatedAt timestamps. A cursor field in the response envelope can be used to retrieve subsequent pages.

Note: Usage records are immutable. They are created automatically by the platform during API operations and cannot be modified or deleted via the API. Use this endpoint for monitoring and auditing purposes only.