Skip to main content
GET
List LLM calls
Back to the Analytics APIs overview Use this endpoint to retrieve the LLM call ledger for a project. The response contains one record for each individual LLM call, including details such as the model, provider, token usage, latency, and cost. The endpoint doesn’t aggregate calls by conversation turn. Each record includes a 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:
  • fromDate and toDate: Required. fromDate is inclusive, while toDate is exclusive.
  • sessionIds: Filter by specific session IDs; up to 10,000.
  • channel: Filter by the exact channel name as stored, such as web_chat or twilio_sms. Shorthand such as web isn’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 as runtime for live agent traffic or evals for evaluation runs. Older spellings are translated.
  • sourceSubtype: Filter by the purpose of the call within its source, such as response_generation or guardrails.
  • status: Filter by success or failed.
  • model: Filter by the exact model ID as recorded, such as gpt-4o. Calls without a model ID use unknown.
  • provider: Filter by model provider, such as openai or azure. Calls without a provider use unknown.
  • environment: Filter by development, staging, production, or working-copy. This endpoint uses development, not dev. Design-time calls have no environment.
  • name: Filter by the exact effective agent name, operation type, or provider fallback.
  • attributionName, attributionType, attributionId, and attributionScope: 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.
All filters other than the date range are optional and match exactly. Filters combine with 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

Use channelUId 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.
For identifier lookups, use List LLM calls using JWE payload. Proxies, load balancers, and browser history can record a GET query string. They don’t record a POST body, and you can encrypt it. Invalid values return a 400 error: Each call in the response includes 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: The canonical fields are omitted for calls recorded before provider token accounting. canonicalAccountingStatus appears only when the call has accounting metadata.

Authorizations

x-api-key
string
header
required

Project-bound API key. Do not send an Authorization header.

Path Parameters

projectId
string
required
Minimum string length: 1

Query Parameters

fromDate
string<date-time>
required
toDate
string<date-time>
required
limit
integer
default:100

How many calls to return. When dataMode=full, a page may come back with fewer rows than requested so the response stays within the 1 MiB size limit — check hasMore rather than assuming a short page is the last one.

Required range: 1 <= x <= 10000
offset
integer
default:0
Required range: x >= 0
sessionIds
string[]

Filter to specific sessions. Pass up to 10,000 session IDs, comma-separated or by repeating the parameter.

Maximum array length: 10000
Minimum string length: 1
channel
enum<string>

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).

Available options:
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
source
enum<string>

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).

Available options:
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
sourceSubtype
enum<string>

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).

Available options:
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
status
enum<string>

Filter to successful or failed calls. Any other value is rejected with 400 INVALID_STATUS.

Available options:
success,
failed
model
string

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).

Minimum string length: 1
provider
string

Filter 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).

Minimum string length: 1
environment
enum<string>

Filter 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).

Available options:
development,
staging,
production,
working-copy
name
string

Exact effective agent name, operation type, or provider fallback.

Minimum string length: 1
channelType
enum<string>

Exact transport-specific channel type.

Available options:
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
attributionName
string

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.

Minimum string length: 1
attributionType
string

Exact attribution type recorded on the call, for example credential or auth_profile.

Minimum string length: 1
attributionId
string

Exact attribution ID recorded on the call. Combine with attributionType to select one credential or auth profile.

Minimum string length: 1
attributionScope
string

Exact attribution scope recorded on the call.

Minimum string length: 1
channelUId
string[]

Filter 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).

Required array length: 1 - 100 elements
Required string length: 1 - 512
dataMode
enum<string>
default:summary

How much detail to return per call. summary returns the facts about each call. full also includes the prompt sent and the response received, under payload, where these were stored.

Available options:
summary,
full
sortBy
enum<string>
default:timestamp
Available options:
timestamp,
latencyMs,
cost,
totalTokens
sortOrder
enum<string>
default:asc
Available options:
asc,
desc

Response

LLM ledger page returned successfully.

success
boolean
required

Always true on a successful response.

statusCode
integer
required

HTTP status code returned by the provider — 200 when the call succeeded.

total
integer
required

Total number of calls matching your filters, across all pages.

Required range: x >= 0
limit
integer
required

The page size applied to this response.

Required range: 1 <= x <= 10000
offset
integer
required

The offset applied to this response.

Required range: x >= 0
dataMode
enum<string>
required

The detail level applied to this response, echoing your request.

Available options:
summary,
full
hasMore
boolean
required

Whether more pages are available after this one.

generations
object[]
required

The LLM calls on this page.

attributionMatch
object

Present only when an attributionName filter matched more than one source.