Token Breakdown

One chat turn can involve several LLM invokes: the model asks for a tool, reads the result, asks for another, and finally answers. Each of those invokes resends the whole conversation so far, so a turn’s token count grows in a way the transaction history cannot explain on its own. This endpoint answers “which tokens produced this charge” for one credit ledger row, one row per invoke.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

Superadmin only. Non-superadmin requests receive 403 Forbidden. The endpoint is read-only and writes no audit record.

It reports tokens, not credits

The response carries no per-step credit or USD figure, and that is a deliberate product decision rather than an omission. Credit economics and token economics are driven by separate logic — credits are not derived from tokens — so splitting a turn’s single authoritative debit across the invokes that produced it can only ever be an estimate. An earlier build did split it proportionally by token count; that under-weights output tokens, which cost three to five times more than input tokens, and about a quarter of multi-step turns failed to reconcile against the ledger. The charge itself is already stated on the ledger row this breakdown was opened from. What this endpoint adds is the token decomposition behind it.

Get token breakdown

string

required

The organization_credit_ledger row id — the id of an entry returned by the credit ledger endpoint.

string

Optional organization scope. Omit it. The owning organization is resolved from the ledger entry itself, so a superadmin who has switched organizations still gets the right rows; supplying a mismatched hint short-circuits that resolution and returns an empty list. The parameter exists for direct API callers that already know the owning organization.

Response

boolean

array

One object per LLM invoke, ordered by iteration ascending.

Show Breakdown row

string

The assistant message this turn produced.

number

1-based invoke index within the turn.

string

number | null

First iteration only; null on later steps, whose input is the previous step’s input plus what was appended.

number | null

First iteration only. Total cost of the tool definitions sent to the model.

object | null

First iteration only. { [toolName]: tokens } — which tool’s schema costs what.

number | null

First iteration only. Retrieved knowledge-base context, already subtracted out of systemPromptTokens (it is injected into the system prompt).

number | null

First iteration only.

number | null

First iteration only.

number | null

First iteration only. Images are counted at a flat approximation — real per-image cost varies by model and resolution.

number | null

Our own count of the input, summed from the components above. First iteration only.

number

The provider’s own input count for this invoke.

number

number | null

number

string

tool_call or text.

string

initial, tool_round, round_cap (tools withheld at the round cap) or empty_retry (the model returned nothing and was re-prompted).

array | null

{ id?, name, args } — what the model asked for on this step.

array | null

{ toolCallId, name, tokens } — the tool results appended after it.

number | null

Steps 2+. The preceding assistant tool-call message added to the context.

number | null

Steps 2+. The tool results added to the context. Usually the dominant term in a turn that grew unexpectedly.

string | null

The external_cost_events row for the turn’s provider charge. Note this is not a credit ledger id.

string

Response

{
  "success": true,
  "data": [
    {
      "id": "6f1c…",
      "conversationId": "c2a1…",
      "messageId": "9b77…",
      "iteration": 1,
      "botId": "b01f…",
      "organizationId": "0d3e…",
      "model": "openai/gpt-4o",
      "systemPromptTokens": 1200,
      "toolSchemasTokens": 800,
      "toolSchemasByTool": { "get_products": 800 },
      "kbContextTokens": 2500,
      "kbChunksCount": 3,
      "historyTokens": 1500,
      "historyTurnsCount": 4,
      "userMessageTokens": 30,
      "attachmentTokens": 0,
      "inputTokensComputed": 6030,
      "inputTokensReported": 6030,
      "outputTokens": 150,
      "totalTokens": 6180,
      "responseType": "tool_call",
      "invokeReason": "initial",
      "toolCallsJsonb": [{ "name": "get_products", "args": { "category": "shoes" } }],
      "externalCostEventId": "3a90…",
      "createdAt": "2026-09-29T10:00:00.000Z"
    },
    {
      "id": "7d24…",
      "iteration": 2,
      "systemPromptTokens": null,
      "inputTokensComputed": null,
      "inputTokensReported": 7500,
      "outputTokens": 400,
      "totalTokens": 7900,
      "responseType": "text",
      "invokeReason": "tool_round",
      "appendedAssistantTokens": 150,
      "appendedToolMessageTokens": 1200,
      "externalCostEventId": "3a90…",
      "createdAt": "2026-09-29T10:00:02.000Z"
    }
  ]
}

Reading `inputTokensComputed` against `inputTokensReported`

Computed counts use the OpenAI tokenizer (cl100k/o200k) for every model. On a Claude or Gemini turn, part of any gap between the two numbers is tokenizer mismatch rather than a real accounting discrepancy. Account for that before reading a gap as signal.

A large gap that is not explained by the tokenizer usually means a component is reaching the model that the breakdown does not attribute — a prompt section added outside the counted path, for example.

Data availability

The underlying table is forward-only with no backfill: historical prompts cannot be reconstructed, so a ledger row from before the feature shipped returns an empty list. Rows are written best-effort after the turn is billed — a failure to record the breakdown never fails a chat turn.

Errors

Status	Meaning
`400`	Missing `Authorization` header, or no organization could be resolved
`401`	Missing, malformed, or expired token
`403`	Caller is not a platform superadmin
`500`	Lookup failed

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Token Breakdown

Token Breakdown

It reports tokens, not credits

Get token breakdown

Response

Reading `inputTokensComputed` against `inputTokensReported`

Data availability

Errors

​Token Breakdown

​It reports tokens, not credits

​Get token breakdown

​Response

​Reading inputTokensComputed against inputTokensReported

​Data availability

​Errors

Token Breakdown

It reports tokens, not credits

Get token breakdown

Response

Reading `inputTokensComputed` against `inputTokensReported`

Data availability

Errors