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 returnusagein 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,outputTokensandtotalTokensare stored as the AI model reports them.reasoningTokensandcachedInputTokensare stored only when the model reports a value above zero; otherwise they arenull. - Times are UTC.
createdAtis when the log was written. PassstartDateandendDateas ISO 8601 timestamps withZor an offset, for example2026-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
aiIdcan 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.workspaceIdnames another workspace is rejected before any field runs, and a field whose ownworkspaceIdnames another workspace (written inline in the query, passed in another variable or sent in a later operation of a batch) fails withThis API key can only access its own workspace.
Token usage log properties
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The log ID. |
aiId | string | The ID of the AI assistant that generated the reply. |
conversationId | string | The ID of the conversation the reply was generated in. |
clientId | string | The ID of the conversation's client. |
messageId | string | The ID of the client message that triggered the reply. Can be |
inputTokens | number | Input tokens the AI model reported for the reply. |
outputTokens | number | Output tokens the AI model reported for the reply. |
totalTokens | number | Total tokens the AI model reported for the reply. |
reasoningTokens | number | Reasoning tokens the AI model reported. |
cachedInputTokens | number | Input tokens the AI model reported as served from its cache. |
createdAt | DateTime | 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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
aiId | string | Filter by AI assistant ID, as returned by |
conversationId | string | Filter by conversation ID. |
clientId | string | Filter by client ID. |
messageId | string | Filter by the ID of the client message that triggered the reply. |
startDate | DateTime | Only logs created at or after this time (inclusive). |
endDate | DateTime | Only logs created at or before this time (inclusive). |
pageInfo argument
Optional second argument. See Pagination for the general rules.
| Attribute | Type | Description |
|---|---|---|
limit | number | Logs per page. Defaults to 50, which is also the maximum: larger values return 50 logs. |
cursor | timestamp | The |
query | string | Not used by this API. |
count | boolean | When |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqquery 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
cursorreturns logs created after it. To read every log, keep passingpageInfo.endCursorascursorwhilehasNextPageistrue. hasNextPageis exact: it istrueonly when at least one more log matches after this page.endCursoris thecreatedAtof the last log on the page, ornullwhen the page is empty.- Date range.
startDateandendDateare both inclusive and compared withcreatedAtin UTC. Set one of them to leave the other side open, or neither to list all logs of the workspace. - Empty fields. Pass
nullforaiId,conversationId,clientIdormessageIdto get logs where that field is empty. If you passnullfor more than one of them, a log matches when any of those fields is empty. - The cursor compares
createdAtonly. If two logs have the samecreatedAt(to the millisecond) and fall on a page boundary, the second one is skipped. Use the Token Usage Total API for exact sums.
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
startDate | DateTime | Required. Sum logs created at or after this time (inclusive). |
endDate | DateTime | Required. Sum logs created at or before this time (inclusive). |
aiId | string | Only sum logs of this AI assistant. A value that is not a valid AI assistant ID returns an error. |
conversationId | string | Only sum logs of this conversation. |
Response fields
| Field | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID from the input. |
totalInputTokens | number | Sum of |
totalOutputTokens | number | Sum of |
totalTokens | number | Sum of |
totalReasoningTokens | number | Sum of |
totalCachedInputTokens | number | Sum of |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqquery 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, nevernull. Logs wherereasoningTokensorcachedInputTokensisnulladd0to those totals. - Date range.
startDateandendDateare both inclusive and compared withcreatedAtin UTC. For a calendar month, use2026-10-01T00:00:00.000Zto2026-10-31T23:59:59.999Z. IfstartDateis afterendDate, every total is0. - Pass
nullforaiIdorconversationIdto total logs where that field is empty. If you passnullfor 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
clientIdormessageIdand add up the logs.
Programming language examples
cURL
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}"}'