Skip to Content
API ReferenceToken Usage

Token Usage APIs

Overview

A token usage log records the AI tokens used to generate one reply of a Bread Crumbs AI assistant (Crumby). Each log links the token counts to the AI assistant, conversation, client and message the reply belongs to, so you can see where AI usage comes from and add it up over a date range.

These APIs are served by the Bot GraphQL endpoint https://gateway.bcrumbs.net/bot/gq and are read-only. The platform writes the logs; there is no API to create, edit or delete them.

  • What creates a log. One log is written each time a Bread Crumbs AI assistant (type bc_ai) generates a reply in a conversation and the AI model reports token usage for it. Assistants of the other AI types (openai, pinecone, custom, bc_flow) don’t create logs. Neither do voice calls or the inbox AI assist APIs (Conversation Summary, Auto-Complete Message, Enhance Message), which return usage in their own response instead.
  • Logged when generated. The log is written when the reply is generated, even if the reply is not sent afterwards (for example, when the client sends a newer message first and only the latest reply goes out). No log is written when the AI call fails.
  • Best effort. The log is written in the background, so it can appear a moment after the reply. If writing it fails, the reply is not affected and that usage is not logged.
  • Token counts come from the AI model. inputTokens, outputTokens and totalTokens are stored as the AI model reports them. reasoningTokens and cachedInputTokens are stored only when the model reports a value above zero; otherwise they are null.
  • Times are UTC. createdAt is when the log was written. Pass startDate and endDate as ISO 8601 timestamps with Z or an offset, for example 2026-10-01T00:00:00.000Z.
  • Not a billing record. Plan usage and message credits are not calculated from token usage logs.
  • Retention. Logs are kept when an AI assistant is deleted, so aiId can point to a deleted assistant. Deleting the workspace deletes its logs.
  • Who can read logs. Any role on the workspace (Owner, Admin, Manager, Agent+ or Agent) can list and total logs. Workspace API keys and agent API keys of any role work too. A user with no role in the workspace gets Missing role assignment for the target user.
  • API keys stay in their workspace. An API key only works in its own workspace. A request whose input.workspaceId names another workspace is rejected before any field runs, and a field whose own workspaceId names another workspace (written inline in the query, passed in another variable or sent in a later operation of a batch) fails with This API key can only access its own workspace.

Token usage log properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The log ID.

aiIdstring

The ID of the AI assistant that generated the reply.

conversationIdstring

The ID of the conversation the reply was generated in.

clientIdstring

The ID of the conversation's client.

messageIdstring

The ID of the client message that triggered the reply. Can be null.

inputTokensnumber

Input tokens the AI model reported for the reply.

outputTokensnumber

Output tokens the AI model reported for the reply.

totalTokensnumber

Total tokens the AI model reported for the reply.

reasoningTokensnumber

Reasoning tokens the AI model reported. null when not reported or zero.

cachedInputTokensnumber

Input tokens the AI model reported as served from its cache. null when not reported or zero.

createdAtDateTime

When the log was written (UTC).

List Token Usage Logs API

Get the token usage logs of a workspace, oldest first (createdAt ascending). Filter by AI assistant, conversation, client, triggering message or date range. Each node is a token usage log.

This endpoint supports pagination. See Pagination for more information.

Access: Any role on the workspace (Owner, Admin, Manager, Agent+ or Agent). Works with workspace API keys and with agent API keys of any role, in the key’s own workspace.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

aiIdstring

Filter by AI assistant ID, as returned by ais. A value that is not a valid AI assistant ID returns an error.

conversationIdstring

Filter by conversation ID.

clientIdstring

Filter by client ID.

messageIdstring

Filter by the ID of the client message that triggered the reply.

startDateDateTime

Only logs created at or after this time (inclusive).

endDateDateTime

Only logs created at or before this time (inclusive).

pageInfo argument

Optional second argument. See Pagination for the general rules.

AttributeTypeDescription
limitnumber

Logs per page. Defaults to 50, which is also the maximum: larger values return 50 logs.

cursortimestamp

The endCursor of the previous page. Returns logs created after it.

querystring

Not used by this API.

countboolean

When true, pageInfo.count holds the total number of logs that match the filters and date range, regardless of the cursor. Otherwise it is null.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
query tokenUsageLogs($input: TokenUsageLogsInput!, $pageInfo: PageInfoInput) { tokenUsageLogs(input: $input, pageInfo: $pageInfo) { nodes { id aiId conversationId clientId messageId inputTokens outputTokens totalTokens reasoningTokens cachedInputTokens createdAt } pageInfo { hasNextPage endCursor count } } } input TokenUsageLogsInput { workspaceId: Int! # Workspace ID. aiId: ID # AI assistant filter. conversationId: ID # Conversation filter. clientId: ID # Client filter. messageId: ID # Triggering message filter. startDate: DateTime # Created at or after (inclusive). endDate: DateTime # Created at or before (inclusive). } input PageInfoInput { limit: Int # Logs per page (default and maximum 50). cursor: Timestamp # endCursor of the previous page. query: String # Not used by this API. count: Boolean # Return the total count in pageInfo.count. }

The query above returns JSON structured like this:

{ "data": { "tokenUsageLogs": { "nodes": [ { "id": "6710b2c4e1f3a90012ab34cd", "aiId": "66f1a2b3c4d5e6f7a8b9c0d1", "conversationId": "conv_123", "clientId": "client_123", "messageId": "msg_123", "inputTokens": 1850, "outputTokens": 142, "totalTokens": 1992, "reasoningTokens": null, "cachedInputTokens": null, "createdAt": "2026-10-17T09:30:04.512Z" }, { "id": "6710b31ae1f3a90012ab34d9", "aiId": "66f1a2b3c4d5e6f7a8b9c0d1", "conversationId": "conv_123", "clientId": "client_123", "messageId": "msg_124", "inputTokens": 2214, "outputTokens": 96, "totalTokens": 2310, "reasoningTokens": null, "cachedInputTokens": 1792, "createdAt": "2026-10-17T09:31:30.087Z" } ], "pageInfo": { "hasNextPage": true, "endCursor": "2026-10-17T09:31:30.087Z", "count": 6 } } } }
  • Order and cursor. Unlike most list APIs, logs come oldest first, and cursor returns logs created after it. To read every log, keep passing pageInfo.endCursor as cursor while hasNextPage is true.
  • hasNextPage is exact: it is true only when at least one more log matches after this page. endCursor is the createdAt of the last log on the page, or null when the page is empty.
  • Date range. startDate and endDate are both inclusive and compared with createdAt in UTC. Set one of them to leave the other side open, or neither to list all logs of the workspace.
  • Empty fields. Pass null for aiId, conversationId, clientId or messageId to get logs where that field is empty. If you pass null for more than one of them, a log matches when any of those fields is empty.
  • The cursor compares createdAt only. If two logs have the same createdAt (to the millisecond) and fall on a page boundary, the second one is skipped. Use the Token Usage Total API for exact sums.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"tokenUsageLogs","variables":{"input":{"workspaceId":12,"conversationId":"conv_123","startDate":"2026-10-01T00:00:00.000Z","endDate":"2026-10-17T23:59:59.999Z"},"pageInfo":{"limit":2,"count":true}},"query":"query tokenUsageLogs($input: TokenUsageLogsInput!, $pageInfo: PageInfoInput) {\n tokenUsageLogs(input: $input, pageInfo: $pageInfo) {\n nodes {\n id\n aiId\n conversationId\n clientId\n messageId\n inputTokens\n outputTokens\n totalTokens\n reasoningTokens\n cachedInputTokens\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'

Token Usage Total API

Get the sum of the token usage logs created in a date range, optionally for one AI assistant or one conversation. Both dates are required.

Access: Any role on the workspace (Owner, Admin, Manager, Agent+ or Agent). Works with workspace API keys and with agent API keys of any role, in the key’s own workspace.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

startDateDateTime

Required. Sum logs created at or after this time (inclusive).

endDateDateTime

Required. Sum logs created at or before this time (inclusive).

aiIdstring

Only sum logs of this AI assistant. A value that is not a valid AI assistant ID returns an error.

conversationIdstring

Only sum logs of this conversation.

Response fields

FieldTypeDescription
workspaceIdnumber

The workspace ID from the input.

totalInputTokensnumber

Sum of inputTokens.

totalOutputTokensnumber

Sum of outputTokens.

totalTokensnumber

Sum of totalTokens.

totalReasoningTokensnumber

Sum of reasoningTokens.

totalCachedInputTokensnumber

Sum of cachedInputTokens.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
query tokenUsageTotal($input: TokenUsageTotalInput!) { tokenUsageTotal(input: $input) { workspaceId totalInputTokens totalOutputTokens totalTokens totalReasoningTokens totalCachedInputTokens } } input TokenUsageTotalInput { workspaceId: Int! # Workspace ID. startDate: DateTime! # Created at or after (inclusive). endDate: DateTime! # Created at or before (inclusive). aiId: ID # AI assistant filter. conversationId: ID # Conversation filter. }

The query above returns JSON structured like this:

{ "data": { "tokenUsageTotal": { "workspaceId": 12, "totalInputTokens": 1284530, "totalOutputTokens": 96412, "totalTokens": 1380942, "totalReasoningTokens": 12850, "totalCachedInputTokens": 742016 } } }
  • Totals are summed from the stored logs on every request.
  • When no log matches, every total is 0, never null. Logs where reasoningTokens or cachedInputTokens is null add 0 to those totals.
  • Date range. startDate and endDate are both inclusive and compared with createdAt in UTC. For a calendar month, use 2026-10-01T00:00:00.000Z to 2026-10-31T23:59:59.999Z. If startDate is after endDate, every total is 0.
  • Pass null for aiId or conversationId to total logs where that field is empty. If you pass null for both, a log matches when either field is empty.
  • Totals are 32-bit integers. If a sum goes over 2,147,483,647, the query returns an error, so split very long date ranges into shorter ones.
  • To total by client or by message, use the List Token Usage Logs API with clientId or messageId and add up the logs.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"tokenUsageTotal","variables":{"input":{"workspaceId":12,"startDate":"2026-10-01T00:00:00.000Z","endDate":"2026-10-31T23:59:59.999Z","aiId":"66f1a2b3c4d5e6f7a8b9c0d1"}},"query":"query tokenUsageTotal($input: TokenUsageTotalInput!) {\n tokenUsageTotal(input: $input) {\n workspaceId\n totalInputTokens\n totalOutputTokens\n totalTokens\n totalReasoningTokens\n totalCachedInputTokens\n }\n}"}'