curl --request GET \
--url https://{host}/api/public/analytics/projects/{projectId}/llm-ledger \
--header 'x-api-key: <api-key>'{
"success": true,
"statusCode": 200,
"total": 1,
"limit": 100,
"offset": 0,
"dataMode": "summary",
"hasMore": false,
"generations": [
{
"id": "sess-1:call-1:2026-08-04T09:59:36.316Z:GPT-5.2:azure:1396:780:11659:0",
"model": "GPT-5.2",
"agentName": "Support Agent",
"provider": "azure",
"environment": "production",
"status": "success",
"inputTokens": 1396,
"cachedTokens": 224,
"cacheWriteTokens": 0,
"completionTokens": 500,
"reasoningTokens": 280,
"outputTokens": 780,
"totalTokens": 2176,
"latencyMs": 11659,
"timeToFirstTokenMs": 0,
"streamingUsed": false,
"cost": 0.42,
"timestamp": "2026-08-04T09:59:36.316Z",
"sessionId": "sess-1",
"callId": "call-1",
"traceId": "trace-1",
"eventId": "event-1",
"source": "runtime",
"sourceSubtype": "response_generation",
"sourceLabel": "Runtime",
"sourceSubtypeLabel": "Response Generation",
"sourceId": "agent-1",
"channel": "web_chat",
"channelType": "web_chat",
"statusCode": 200,
"payloadState": "available"
}
]
}List LLM calls
List the individual LLM calls made in a project, with their model, provider, token counts, latency, and cost.
curl --request GET \
--url https://{host}/api/public/analytics/projects/{projectId}/llm-ledger \
--header 'x-api-key: <api-key>'{
"success": true,
"statusCode": 200,
"total": 1,
"limit": 100,
"offset": 0,
"dataMode": "summary",
"hasMore": false,
"generations": [
{
"id": "sess-1:call-1:2026-08-04T09:59:36.316Z:GPT-5.2:azure:1396:780:11659:0",
"model": "GPT-5.2",
"agentName": "Support Agent",
"provider": "azure",
"environment": "production",
"status": "success",
"inputTokens": 1396,
"cachedTokens": 224,
"cacheWriteTokens": 0,
"completionTokens": 500,
"reasoningTokens": 280,
"outputTokens": 780,
"totalTokens": 2176,
"latencyMs": 11659,
"timeToFirstTokenMs": 0,
"streamingUsed": false,
"cost": 0.42,
"timestamp": "2026-08-04T09:59:36.316Z",
"sessionId": "sess-1",
"callId": "call-1",
"traceId": "trace-1",
"eventId": "event-1",
"source": "runtime",
"sourceSubtype": "response_generation",
"sourceLabel": "Runtime",
"sourceSubtypeLabel": "Response Generation",
"sourceId": "agent-1",
"channel": "web_chat",
"channelType": "web_chat",
"statusCode": 200,
"payloadState": "available"
}
]
}traceId and an eventId that you can use with List trace events to get the full execution context.
Use the dataMode parameter to control the level of detail returned. The default mode returns call-level facts, while full additionally includes the exact prompt and response payloads when available.
Authenticate with the x-api-key header. The key must be bound to the project you are querying and have the analytics:read permission.
The available filtering criteria are:
fromDateandtoDate: Required.fromDateis inclusive, whiletoDateis exclusive.sessionIds: Filter by specific session IDs; up to 10,000.channel: Filter by the exact channel name as stored, such asweb_chatortwilio_sms. Shorthand such aswebisn’t expanded. Design-time calls, such as Studio test calls, have no channel.channelType: Filter by the exact transport-specific channel type.source: Filter by the part of the platform that made the call, such asruntimefor live agent traffic orevalsfor evaluation runs. Older spellings are translated.sourceSubtype: Filter by the purpose of the call within its source, such asresponse_generationorguardrails.status: Filter bysuccessorfailed.model: Filter by the exact model ID as recorded, such asgpt-4o. Calls without a model ID useunknown.provider: Filter by model provider, such asopenaiorazure. Calls without a provider useunknown.environment: Filter bydevelopment,staging,production, orworking-copy. This endpoint usesdevelopment, notdev. Design-time calls have no environment.name: Filter by the exact effective agent name, operation type, or provider fallback.attributionName,attributionType,attributionId, andattributionScope: Filter by the credential, auth profile, or other source that the call is attributed to.channelUId: Filter by the identifier of the end user in the conversation, such as an email address or phone number. Up to 100 values. See Filter by end user.
AND. An empty filter value returns 400 INVALID_FILTER.
Use sortBy (timestamp, latencyMs, cost, or totalTokens) and sortOrder (asc by default, or desc) to order the results. Use limit (1 to 10,000, default 100) and offset to page through them. With dataMode=full, a page can hold fewer calls than limit so the response stays within 1 MiB. Check hasMore instead of assuming that a short page is the last one. The cost value is an estimate in USD.
Filter by end user
UsechannelUId to find the LLM calls made in conversations with a given end user. The value is the channel user ID that the channel reported for the user, such as an email address, phone number, or SIP URI.
- Pass up to 100 values, comma-separated or by repeating the parameter. A call matches when it matches any value.
- Send the full identifier. Partial and prefix searches aren’t supported.
- Emails match case-insensitively.
- Write phone numbers in international format with the country code, such as
+14155550100. A national number matches only an identical identifier stored the same way. - Only calls recorded after this filter was released carry the identifier. Older calls never match.
- A match is evidence, not proof of identity. Phone numbers and email addresses are reassigned over time.
400 error:
| Error code | Cause |
|---|---|
INVALID_CHANNEL_UID | A value is empty, isn’t a string, contains a control character, is longer than 512 characters, or is longer than 256 characters after normalization. The message names the position of the value and never repeats it. |
TOO_MANY_FILTER_VALUES | The request has more than 100 values. The count includes duplicates. |
channelUId, the normalized identifier of the end user. This is personal data. The value is null when the call has no end user, such as a design-time or pipeline call, when the channel didn’t identify the user, or when the call predates the field.
Token and accounting fields
Each call record includes these token and accounting fields:| Field | Description |
|---|---|
cacheWriteTokens | Input tokens that the provider wrote to its prompt cache on this call. They are part of inputTokens, and they are priced at the cache-write rate when one is configured. null means the provider didn’t report cache writes, as with Azure Chat, or the call predates provider token accounting. 0 means the provider reported zero. |
canonicalTokenUsage | Optional. A versioned usage record for the call with input, output, total, cache write, cache read, and reasoning quantities. Each quantity has a status and a provider source. |
canonicalCostEstimate | Optional. The cost estimate stored for the call, with its status, currency, and the pricing snapshot used. The API never recalculates it from current prices. |
canonicalAccountingStatus | Optional. The validation state of the stored accounting: usage and estimate, each valid, legacy, invalid, or unsupported. usageReason and estimateReason explain a state. |
canonical fields are omitted for calls recorded before provider token accounting. canonicalAccountingStatus appears only when the call has accounting metadata.Authorizations
Query Parameters
Filter by the channel the conversation took place on. Design-time calls, such as Studio test calls, are not tied to a channel and will not match any channel filter.
Matched exactly as stored, with no alias handling. Unlike the sessions
endpoint, shorthand such as web or sms is not expanded here — use the
exact channel name such as web_chat or twilio_sms.
Not restricted to a fixed list, so an unrecognised value returns no results
rather than an error. Cannot be empty (400 INVALID_FILTER).
http_async, slack, line, msteams, whatsapp, messenger, instagram, twilio_sms, zendesk, telegram, genesys, genesys_open_messaging, ai4w, kore_agent_assist, email, voice_vxml, korevg, audiocodes, genesys_audio_connector, voice_pipeline, voice_realtime, voice, voice_twilio, voice_livekit, ag_ui, a2a, sdk_websocket, web_debug, web_chat, api, http Filter by which part of the platform made the call — for example runtime
for live agent traffic, or evals for evaluation runs.
You can pass either the current name or an older one; the older spellings
listed under x-alias-groups are translated for you, and matching is
case-insensitive with - and spaces treated as _. So agent_session
finds the same calls as runtime.
Not restricted to a fixed list, so an unrecognised value returns no results
rather than an error. Cannot be empty (400 INVALID_FILTER).
runtime, runtime_internal, arch, evals, pipelines, guardrails, knowledge, studio_test_calls, channels, agent_session, eval, analytics_pipeline, analytics_query, guardrail, search_ai, prompt_library, model_health, model_admin, health:credential-store, sdk_widget_localization Filter by the specific purpose of the call within its source — for example
response_generation for replies to users, or guardrails for safety
checks.
Older spellings are translated for you, as listed under x-alias-groups. If
you also pass source, translation is limited to that source's subtypes; on
its own, subtype names are resolved across all sources.
Not restricted to a fixed list, so an unrecognised value returns no results
rather than an error. Cannot be empty (400 INVALID_FILTER).
response_generation, conversation_history_compaction, ner_gather_llm_extraction, model_based_pii_entity_recognizer, model_entity_preview, llm_backed_validation, searchai_kb_query_intelligence, searchai_query_assistance, routing_pipeline, pipeline_classifier, pipeline_tool_filter, pipeline_merge, contextual_filler_generation, tool_result_summarization, sip_handoff_summary, semantic_execution, legacy_nlu_fallback, general_assistance, project_assistance, eval_remediation, evaluation_suite_generation, natural_language_analytics_query, text_to_sql, guardrails, studio_test_calls, widget_copy_translation, tool_use_iteration, response_gen, realtime_response, conversation_compaction, nlu_entity_extraction, kb_classify_rewrite, field_validation, agent_building, eval_suite_creation, eval_design_time_asset_generation, nl_to_sql, nl_query, query_intelligence, prompt_test, prompt_experiment, credential_health_check, translation_generation Filter by model, using the exact model id as recorded, such as gpt-4o.
There is no fixed list, because each tenant can register its own models.
Calls recorded without a model id appear as unknown and can be found with
model=unknown. Cannot be empty (400 INVALID_FILTER).
1Filter by model provider, such as openai or azure. Calls recorded
without a provider appear as unknown and can be found with
provider=unknown.
Not restricted to a fixed list, so an unrecognised value returns no results
rather than an error. The values below are the providers the platform can
call. Cannot be empty (400 INVALID_FILTER).
1Filter by environment. Note that this endpoint stores development rather
than dev — unlike the sessions endpoint, which uses dev. Design-time
calls, such as Studio test calls, are not tied to an environment and will
not match this filter.
Matched exactly as stored. Not restricted to a fixed list, so an
unrecognised value returns no results rather than an error. Cannot be empty
(400 INVALID_FILTER).
development, staging, production, working-copy Exact transport-specific channel type.
http_async, slack, line, msteams, whatsapp, messenger, instagram, twilio_sms, zendesk, telegram, genesys, genesys_open_messaging, ai4w, kore_agent_assist, email, voice_vxml, korevg, audiocodes, genesys_audio_connector, voice_pipeline, voice_realtime, voice, voice_twilio, voice_livekit, ag_ui, a2a, sdk_websocket, web_debug, web_chat, api, http Display name of the credential, auth profile or other source the call is attributed to. Matched case-insensitively against the name after trimming. When the name matches more than one source, all of them are included and the response carries attributionMatch.
1Filter to calls made in conversations with a given end user, identified by their channel user ID: the email address, phone number, SIP URI or other identifier the channel reported for that user. Pass up to 100 values, comma-separated or by repeating the parameter. A call matches when it matches any value, and the filter combines with every other filter.
Each value must be the full identifier; partial or prefix searches are
not supported. Emails match case-insensitively. Phone numbers must be in
international format with the country code (for example +14155550100);
a national number without a country code matches only an identical
identifier stored the same way. Only calls recorded after this filter was
released carry the identifier, so older calls never match.
A match is evidence, not proof: phone numbers and email addresses are reassigned over time, and a channel reports what the user's device or account supplied.
Prefer the POST form of this endpoint for identifier lookups: a GET query string can be recorded by proxies, load balancers and browser history, while a POST body is not (and can be encrypted).
Errors: 400 INVALID_CHANNEL_UID when a value is empty, not a string,
contains a control character, is longer than 512 characters, or is longer
than 256 characters after normalization; the message names the value's
position and never repeats the value. 400 TOO_MANY_FILTER_VALUES when
more than 100 values are sent (counted before duplicates are removed).
1 - 100 elements1 - 512Response
LLM ledger page returned successfully.
- Option 1
- Option 2
Was this page helpful?