Usage
Usage accounting
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
| In webhook payloads | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
promptTokens | integer (int32) | Optional | Prompt-token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
completionTokens | integer (int32) | Optional | Completion-token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
totalTokens | integer (int32) | Optional | Total token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
costEstimate | number (float) or string (NaN, Infinity, -Infinity) | Optional | Estimated cost in USD. |
completionTokensDetails | CompletionTokensDetails | Optional | Breakdown of completion tokens. |
promptTokensDetails | PromptTokensDetails | Optional | Breakdown of prompt tokens (cache). |
costDetails | CostDetails | Optional | Breakdown of upstream provider cost (BYOK routes). |
isByok | boolean | Optional | Whether this generation used the customer's own model-provider key. |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
promptTokens | integer (int32) | Optional | Prompt-token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
completionTokens | integer (int32) | Optional | Completion-token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
totalTokens | integer (int32) | Optional | Total token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
costEstimate | number (float) or string (NaN, Infinity, -Infinity) | Optional | Estimated cost in USD. |
completionTokensDetails | CompletionTokensDetails | Optional | Breakdown of completion tokens. |
promptTokensDetails | PromptTokensDetails | Optional | Breakdown of prompt tokens (cache). |
costDetails | CostDetails | Optional | Breakdown of upstream provider cost (BYOK routes). |
isByok | boolean | Optional | Whether this generation used the customer's own model-provider key. |
In webhook payloads
Webhook JSON uses protobuf field names (snake_case).
| Field | Type | Presence | Meaning |
|---|---|---|---|
prompt_tokens | integer (int32) | Optional | Prompt-token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
completion_tokens | integer (int32) | Optional | Completion-token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
total_tokens | integer (int32) | Optional | Total token usage reported by the model provider. Minimum: -2147483648. Maximum: 2147483647. |
cost_estimate | number (float) or string (NaN, Infinity, -Infinity) | Optional | Estimated cost in USD. |
completion_tokens_details | CompletionTokensDetails | Optional | Breakdown of completion tokens. |
prompt_tokens_details | PromptTokensDetails | Optional | Breakdown of prompt tokens (cache). |
cost_details | CostDetails | Optional | Breakdown of upstream provider cost (BYOK routes). |
is_byok | boolean | Optional | Whether this generation used the customer's own model-provider key. |
Where used
| Reference | Relationship |
|---|---|
| Append a message without generating | POST /api/v1/llm/append-message |
| Send a message to a conversation | POST /api/v1/llm/send-message |
| Send a message and wait for the result | POST /api/v1/llm/send-message-sync |
| Withdraw your rating on a message | POST /api/v1/llm/delete-message-rating |
| Get full conversation state | POST /api/v1/llm/conversation-state |
| Rate an assistant message | POST /api/v1/llm/rate-message |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-sync |
| llm.generation_completed | Webhook JSON uses protobuf field names (snake_case). |
| llm.message_published | Webhook JSON uses protobuf field names (snake_case). |
| LLMGenerationCompletedEvent | Nested in model |
| Message | Nested in model |
| Message | Nested in model |
| Message | Nested in model |
| UsageByModel | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-usage.