List session summaries

Use limit and offset to page through the results. The response includes message, trace-event, and token counts per session, but not the messages or trace details themselves. Use the conversation-history endpoint for messages and the traces endpoint for execution detail.

GET /api/public/analytics/projects/{projectId}/sessions

List session summaries

cURL

curl --request GET \
  --url https://{host}/api/public/analytics/projects/{projectId}/sessions \
  --header 'x-api-key: <api-key>'

200

{
  "success": true,
  "total": 1,
  "offset": 0,
  "limit": 100,
  "hasMore": false,
  "sessions": [
    {
      "id": "sess-01J4S8Y1",
      "channel": "web_chat",
      "environment": "production",
      "status": "ended",
      "containmentType": "contained_resolved",
      "createdAt": "2026-08-01T00:00:00.000Z",
      "lastActivityAt": "2026-08-01T00:05:00.000Z",
      "endedAt": "2026-08-01T00:05:30.000Z",
      "messageCount": {
        "user": 3,
        "agent": 4,
        "total": 7
      },
      "traceEventCount": {
        "llm_call": 2,
        "decision": 1,
        "tool_call": 5,
        "error": 1,
        "total": 12
      },
      "tokenCount": {
        "inputTokens": 100,
        "cachedTokens": 10,
        "completionTokens": 32,
        "reasoningTokens": 8,
        "outputTokens": 40,
        "totalTokens": 140
      },
      "traceDimensions": {
        "accountTier": "gold"
      },
      "estimatedCost": 0.0025,
      "durationMs": 330000,
      "idleDurationMs": 30000,
      "isTest": null
    }
  ]
}

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

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 belonging to specific end users, using the identity recorded for them on the channel. Pass up to 100 values, comma-separated or by repeating the parameter.

Maximum array length: 100

Minimum string length: 1

channel · enum<string>[]

Filter by the channel the conversation came in on. Pass one or more values, comma-separated or by repeating the parameter, up to 50 distinct channels of 128 characters each.

This endpoint understands shorthand. Values are grouped into channel families before matching, and each family also matches its older stored spellings, so channel=web, channel=sdk_web, and channel=web_chat all return the same web-chat sessions. The groupings are listed under x-alias-groups, and those alias spellings are accepted here even though they are not in the enum — the enum is kept identical across all the public analytics endpoints so there is one channel list to learn.

Because of that grouping, asking for one specific voice channel such as channel=voice_pipeline returns all voice sessions, not just that transport. Use the traces endpoint if you need to distinguish them.

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

Maximum array length: 50

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

Maximum string length: 128

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

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

200

application/json

Session page returned successfully.

success · boolean · required

Always true on a successful response.

sessions · object[] · required

The sessions on this page.

Show child attributes

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.