Skip to main content
GET
List session summaries
Back to the Analytics APIs overview Use this endpoint to retrieve session-level analytics for a project. Each result represents one conversation session and includes summary information such as the source, channel, channel type, environment, status, containment outcome, disposition code, message and trace-event counts, token usage, cost, session duration, and voice call quality. The response doesn’t include the individual messages or trace details. Use List conversation messages and List trace events to retrieve those details. Authenticate with the x-api-key header. The key must be bound to the project you are querying and have the session:read permission.
Without a source filter, this endpoint returns only user_initiated sessions, which are real end-user sessions. Earlier versions returned sessions of every source, including evaluation runs, Studio debug chats, workflow runs, synthetic traffic, and Insights demo data. Send source=all to get every source. The channel filter also changed. See Source and Channel and channel type.
It provides the following filters:
  • fromDate: Inclusive start timestamp.
  • toDate: Exclusive end timestamp.
  • sessionIds: Filter by specific session IDs; up to 10,000.
  • containmentType: Filter by how the session was resolved, such as contained_resolved, contained_partial, escalated, abandoned, or failed. Values are case-sensitive.
  • environment: Filter by environment: dev, staging, production, or working-copy. Use dev, not development.
  • channelUId: Filter by the channel identifier of the end user, such as an email address or phone number. Up to 100 values. See Filter by end user.
  • callerNumber: Filter by the caller number (ANI) or provider caller ID. Up to 100 values. See Filter by caller number.
  • channel: Filter by the exact channel ID the session entered through, such as slack, voice_pipeline, or web_chat. Up to 50 channels. The filter doesn’t group channels into families. See Channel and channel type.
  • channelType: Filter by the type of channel: messaging, voice, sdk, webhook, protocol, or workflow. For example, channelType=voice returns every voice session.
  • source: Filter by why the session exists, such as user_initiated, workflow, eval, synthetic, debug, or demo_insights. The default is user_initiated. Send all for every source. See Source.
  • traceDimensions[key]: Filter by custom session dimensions and their values.
  • status: Filter by session state, such as active, idle, ended, completed, escalated, or abandoned. Pass a single value. The value failed is not accepted as a filter.
  • dispositionCode: Return only sessions with this wrap-up code, which the human agent chose in after-contact work. Pass a single value, up to 200 characters. The match is exact and case-sensitive. Use the code exactly as it appears in dispositionCode on a returned session.
You must provide either fromDate and toDate together, or sessionIds. All other filters are optional. Multiple filters are combined with AND logic; multiple values within a filter are combined with OR logic. Use limit (1 to 10,000, default 100) and offset to paginate through the results. A page can hold fewer sessions than limit so the response stays within 1 MiB. Check hasMore instead of assuming that a short page is the last one.

Source

The source filter says why a session exists. Pass one or more values, comma-separated or by repeating the parameter, up to 100. Matching ignores case and surrounding spaces.
  • user_initiated: Real end-user sessions. This is the default when you omit source or send an empty value.
  • workflow: Workflow runs.
  • eval: Evaluation runs.
  • synthetic: Synthetic traffic.
  • debug: Studio debug chats.
  • demo_insights: Insights demo data.
  • all: Every source. You can’t combine all with another value.
  • production: A legacy name for user_initiated. Send user_initiated in new calls.
Filtering on user_initiated also returns sessions stored with the older value production or with no source. A value outside this list returns 400 INVALID_SOURCE, and the message lists the allowed values.

Channel and channel type

The channel filter matches the exact channel ID. Each ID also matches the older stored spellings of the same ID. For example, channel=web_chat also matches sessions stored as webchat. The filter doesn’t group channels into families. channel=voice_pipeline returns only voice-pipeline sessions. Use channelType to filter by family. For example, channelType=voice returns every voice session. Sessions created before v1.10.0 aren’t backfilled. They keep the coarse channel they were stored with, which is web_chat, voice, or api, and the channel filter matches only that value. For example, channel=voice returns only older sessions stored as voice. These sessions report a channelType only when their channel names one. A session stored as web_chat or api matches no channelType, because several channel types reported those values. Pass up to six channelType values. A value outside the list returns 400 INVALID_CHANNEL_TYPE, and the message lists the allowed values.

Filter by end user

Use channelUId to find the sessions of specific end users. The value is the identifier that the channel supplied for the user: an email address, phone number, SIP address, or provider ID. It can also be the externalUserId that an integrator passed when the session started.
  • Pass up to 100 values, comma-separated or by repeating the parameter.
  • Values are normalized before matching. Priya@Example.com and priya@example.com match. +1 (415) 555-0100, 14155550100, and tel:+14155550100 match the same phone number.
  • Phone numbers must include the country code. A national number without one matches only as a provider ID.
  • Matching is exact on the whole identifier. Partial and prefix matches aren’t supported.
  • A match is evidence, not proof of identity. Phone numbers and email addresses are reassigned over time.
  • channelUId no longer matches the internal contact, customer, or anonymous identifiers recorded on the session.
  • Sessions created before this feature have no channelUId. Find them with sessionIds or a date range.
For identifier lookups, use List session summaries using JWE payload. Proxies and access logs can record a GET query string. An empty or invalid value returns 400 INVALID_CHANNEL_UID.

Filter by caller number

Use callerNumber to find the sessions of specific callers. The value is the caller number (ANI) or the provider caller ID.
  • Pass up to 100 values, comma-separated or by repeating the parameter. Spaces after commas are allowed. The limit counts entries before duplicates are merged. A value that contains a comma can’t be queried, because commas always separate values.
  • Paste the value in any format that the provider, a transcript, or a call detail record shows. The API cleans the value to the same match key that the platform stored at call time.
  • Phone-like values, including sip: and tel: URIs, become E.164 numbers. The API removes spaces, dashes, dots, slashes, parentheses, invisible characters, and a national trunk (0) after the country code. For example, +44 (0)20 7946 0958 matches +442079460958.
  • A value of 7 to 15 bare digits is treated as an international number. For example, 919876543210 matches +919876543210.
  • Digits written in a national format keep their digits. For example, 098765 43210 matches 09876543210.
  • Other values, such as softphone usernames, SDK IDs, or Anonymous, match as cleaned text. Anonymous matches every withheld-number call in the time range.
  • Matching is exact and case-sensitive. anonymous doesn’t match Anonymous, and +14155550100 ext 12 doesn’t match +14155550100. Non-ASCII digits aren’t converted to ASCII.
  • The API doesn’t infer the country. 9876543210 doesn’t match a stored +919876543210, and it doesn’t convert 00 or 011 dial prefixes. Send the full international form.
  • In a URL, send + as %2B, or use the POST form. An unencoded + decodes to a space, which gives the same match.
  • The filter matches only sessions whose summary was written after the filter was released. For earlier sessions, use List conversation messages. Playground and Studio debug sessions never match.
The API never returns the value in a response. A request that uses callerNumber returns 403 CALLER_NUMBER_LOOKUP_DISABLED when the project’s reporting exposure configuration disables the identity field group.

Response fields

Each session in the response includes these fields: The voice object has one value for each Voice Analytics dashboard card. A metric that the call didn’t measure is null, never 0.

Errors

Invalid filter values return a 400 error:

Authorizations

x-api-key
string
header
required

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

Path Parameters

projectId
string
required

Project identifier bound to the API key.

Minimum string length: 1

Query Parameters

fromDate
string<date-time>

Inclusive ISO 8601 start timestamp. Required with toDate unless sessionIds is supplied.

toDate
string<date-time>

Exclusive ISO 8601 end timestamp. Required with fromDate unless sessionIds is supplied.

sessionIds
string[]

Filter to specific sessions. Pass up to 10,000 session IDs, comma-separated or by repeating the parameter. Can be used instead of a date range.

Maximum array length: 10000
Minimum string length: 1
containmentType
enum<string>[]

Filter by how the session was resolved — whether the agent handled it or it went to a human. Pass one or more values, comma-separated or by repeating the parameter, up to 100.

Values are case-sensitive and anything else is rejected with 400 INVALID_CONTAINMENT_TYPE.

Maximum array length: 100
Available options:
contained,
contained_resolved,
contained_partial,
contained_unresolved,
escalated,
abandoned,
failed
environment
enum<string>[]

Filter by environment. Pass one or more values, comma-separated or by repeating the parameter.

Values are case-sensitive and anything else is rejected with 400 INVALID_ENVIRONMENT. Use dev, not development or prod — the service handles both stored spellings for you behind the scenes, but only accepts the four values below as input.

Maximum array length: 4
Available options:
dev,
staging,
production,
working-copy
Maximum string length: 128
channelUId
string[]

Filter to sessions of specific end users by their channel user identifier (channelUId): the email address, phone number, SIP address or provider id the channel supplied for them, or the externalUserId an integrator passed when the session started. Values are normalized before matching, so Priya@Example.com and priya@example.com match, and +1 (415) 555-0100, 14155550100 and tel:+14155550100 match the same phone number. Phone numbers must include the country code; a national number without one matches only as a provider id. Matching is exact on the whole identifier (no partial or prefix match). A match is evidence, not proof of identity: numbers and emails get reassigned. Pass up to 100 values, comma-separated or by repeating the parameter. Prefer the POST operation for identifier lookups: GET query strings can be recorded by proxies and access logs.

Changed in this release: channelUId no longer matches the internal contact, customer or anonymous identifiers recorded on the session. Sessions created before this feature have no channelUId and cannot be found by it; use sessionIds or a date range for them. An empty or invalid value returns 400 INVALID_CHANNEL_UID.

Maximum array length: 100
Minimum string length: 1
callerNumber
string[]

Filter to sessions from specific callers (ANI or provider caller id). Pass up to 100 values, comma-separated (spaces after commas are allowed) or by repeating the parameter; the filter is ANDed with every other filter. The 100-value limit counts entries before duplicates are merged; more returns 400 TOO_MANY_FILTER_VALUES. A value that itself contains a comma cannot be queried, because commas always separate values.

Paste the value in any format the provider, a transcript, a CDR or a spreadsheet shows. Each value is turned into the same match key the platform stored at call time: invisible characters, fullwidth digits and Unicode dashes are cleaned up, a national trunk (0) after the country code is removed (+44 (0)20 7946 0958 matches +442079460958), and phone-like values (including sip: and tel: URIs, spaces, dashes, dots, slashes and parentheses) become E.164. 7 to 15 bare digits are treated as an international number (919876543210 matches +919876543210). Digits written in a national format keep their digits (098765 43210 matches 09876543210). Other values, such as softphone usernames, SDK ids or Anonymous, are matched as cleaned text. Matching is exact and case-sensitive: anonymous does not match Anonymous, and +14155550100 ext 12 does not match +14155550100. Non-ASCII digits such as Arabic-Indic digits are not converted to ASCII. Keys longer than 128 characters are truncated, the same way they were when stored.

There is no country inference: a national number without its country code (9876543210) does not match a stored +919876543210, and 00 or 011 dial prefixes are not converted. Send the full international form where possible. Send + as %2B or use the POST twin; an unencoded + decodes to a space, which is also accepted and gives the same match. Anonymous matches every withheld-number call in the window.

An entry that is empty or has no letter or digit (for example callerNumber=, a trailing comma, or only +), or an entry longer than 512 characters, returns 400 INVALID_CALLER_NUMBER. The value is never returned in the response. When the project's reporting exposure config disables the identity field group, a request with this parameter returns 403 CALLER_NUMBER_LOOKUP_DISABLED.

Coverage: matches sessions whose summary was written after this filter shipped. Sessions recorded earlier are not returned for callerNumber (use /conversation-history, which reads the session record directly). Playground and Studio debug sessions are never matched.

Maximum array length: 100
Required string length: 1 - 512
channel
enum<string>[]

Filter by the channel the session entered through. Pass one or more values, comma-separated or by repeating the parameter, up to 50 distinct channels of 128 characters each.

Matches the exact channel id. Each id also matches the older stored spellings of the same id, listed under x-alias-groups (for example channel=web_chat also matches sessions stored as webchat). Those spellings are accepted here even though they are not in the enum.

Channels are not grouped into families: channel=voice_pipeline returns only voice-pipeline sessions, and channel=voice returns only older sessions stored as voice. Use channelType to filter by family. Before release 1.10.0 this filter grouped channels, so channel=voice_pipeline returned every voice session.

Sessions created before release 1.10.0 are stored with a coarse channel (web_chat, voice, api) and match only that value.

Not restricted to a fixed list, so an unrecognised value returns no results rather than an error.

Maximum array length: 50
Available options:
slack,
line,
msteams,
a365,
whatsapp,
messenger,
instagram,
telegram,
twilio_sms,
zendesk,
genesys,
genesys_open_messaging,
email,
ai4w,
kore_agent_assist,
web_debug,
voice_realtime,
voice_pipeline,
voice_vxml,
audiocodes,
genesys_audio_connector,
korevg,
voice_twilio,
voice_livekit,
sdk_web,
sdk_mobile,
sdk_api,
direct_api,
http_async,
ag_ui,
a2a,
workflow,
eval_simulation,
voice,
web_chat,
api
Maximum string length: 128
source
enum<string>[]

Filter by why the session exists. Pass one or more values, comma-separated or by repeating the parameter, up to 100. Matching ignores case and surrounding spaces.

Default user_initiated. Without this parameter (or with an empty value) only real end-user sessions are returned. all returns every Source and cannot be combined with another value. Filtering on user_initiated also returns sessions stored with the older value production or with no Source; production is still accepted as a filter value and means user_initiated. production is a legacy value: send user_initiated in new calls.

Anything else is rejected with 400 INVALID_SOURCE; the message lists the allowed values.

Maximum array length: 100
Available options:
user_initiated,
workflow,
eval,
synthetic,
debug,
demo_insights,
production,
all
channelType
enum<string>[]

Filter by the type of the channel the session entered through. Pass one or more values, comma-separated or by repeating the parameter. Matching ignores case and surrounding spaces. Omit it for every Channel Type.

A session matches on its stored Channel Type. A session stored before Channel Type existed matches when its channel names that type (the older voice is voice); one stored as web_chat or api matches no Channel Type, because several channel types reported those values.

Anything else is rejected with 400 INVALID_CHANNEL_TYPE; the message lists the allowed values.

Maximum array length: 6
Available options:
messaging,
voice,
sdk,
webhook,
protocol,
workflow
traceDimensions[key]
string

Filter by a custom dimension recorded against the session. Replace key with the dimension name — for example traceDimensions[accountTier]=gold. Repeat with different keys to require all of them. Values match exactly. Remember to URL-encode the brackets if your HTTP client does not do it for you.

status
enum<string>

Filter by the session's current state. Pass a single value; if you repeat the parameter only the first value is used.

Case-sensitive, and anything else is rejected with 400 INVALID_STATUS. Note that sessions can be stored with a status of failed, but failed is not accepted as a filter value here.

Available options:
active,
idle,
ended,
completed,
escalated,
abandoned,
archived
dispositionCode
string

Return only sessions whose dispositionCode equals this value: the wrap-up code the human agent chose in after-contact work. Pass a single value; if you repeat the parameter only the first value is used. Surrounding whitespace is trimmed and an empty value means no filter.

Exact and case-sensitive, like status: resolved does not match Resolved. Codes are the contact centre's own labels, so use the value exactly as it appears in dispositionCode on a returned session. Longer than 200 characters is rejected with 400 INVALID_DISPOSITION_CODE.

Maximum string length: 200
limit
integer
default:100

How many sessions to return. A page may come back with fewer 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

Response

Session page returned successfully.

success
boolean
required

Always true on a successful response.

sessions
object[]
required

The sessions on this page.

total
integer
required

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

Required range: x >= 0
offset
integer
required

The offset applied to this response.

Required range: x >= 0
limit
integer
required

The page size applied to this response.

Required range: 1 <= x <= 10000
hasMore
boolean
required

Whether more pages are available after this one.