> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List session summaries using JWE payload

> List session summaries with the query parameters in a JSON or encrypted JWE request body instead of the URL.

[Back to the Analytics APIs overview](https://koreai.mintlify.site/agent-platform/api-reference/analytics-overview.md)

Use this endpoint to retrieve the same session-level analytics as the [corresponding GET operation](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries), but send the query parameters in a JSON request body instead of the URL query string. It supports the same filters, pagination, validation, permissions, and response format as the GET operation.

Use the `POST` endpoint when the request parameters must be encrypted. With request encryption enabled for the Platform Key, send the query object as a JWE encrypted request. With request encryption disabled, send the parameters as a plain JSON object. Response encryption is independent of request encryption; when enabled, responses other than `401` are returned as encrypted JWE payloads.

Set `Content-Type` to `application/json` or `application/jose+json`. Don't add a query string to the request. Send `traceDimensions` as an object of dimension names and values, for example `{"traceDimensions": {"accountTier": "gold"}}`.

Send `source` and `channelType` as a string, a JSON array, or a comma-separated string. `source` defaults to `user_initiated`, as in the GET operation. Send `channelUId` as a JSON array or a comma-separated string. Each array entry is one value and isn't split on commas. This POST form is the recommended way to look up an end user, because the identifier stays out of URLs that proxies and access logs can record. Send `dispositionCode` as a string of up to 200 characters. Send `callerNumber` as a JSON array of caller values in any provider format, or as a comma-separated string. You don't need URL encoding, so `+` is safe. Each entry must have at least one letter or digit and at most 512 characters. An empty array returns `400`. For the matching rules, see [Filter by caller number](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries#filter-by-caller-number).

For filter details, see the [GET endpoint help article](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries). The same sections cover [Source](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries#source), [Channel and channel type](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries#channel-and-channel-type), and [Filter by end user](https://koreai.mintlify.site/agent-platform/api-reference/analytics-list-session-summaries#filter-by-end-user).


## OpenAPI

````yaml agent-platform/api-specs/sessions.yaml post /api/public/analytics/projects/{projectId}/sessions
openapi: 3.1.0
info:
  title: ABL Public Analytics Sessions API
  version: 1.0.0
  summary: Retrieve project-scoped session analytics.
  description: >
    Returns one row per conversation session in a project, summarising how it
    went:

    which channel it came in on, how it ended, how many messages were exchanged,
    how

    many tokens were used, and what it cost.


    Give either a date range (`fromDate` and `toDate` together) or a list of

    `sessionIds`. Other filters are optional. Different filters combine with
    AND, and

    multiple values in the same filter combine with OR — so

    `channel=web_chat,voice&status=ended` means web chat or voice sessions that
    have

    ended.


    Authenticate with the `x-api-key` header. The key must be bound to the
    project you

    are querying and have `session:read` permission.


    ## Source, channel and Channel Type


    Every session reports its `source` (why it exists), its `channel` (the
    channel it

    entered through) and its `channelType`.


    - **Default Source changed.** Without a `source` filter the API now returns
    only
      `user_initiated` sessions (real end-user traffic). It used to return sessions of
      every Source, including evaluation runs, Studio debug chats, workflow runs,
      synthetic traffic and Insights demo data. Send `source=all` for every Source.
    - **`channel` filter is exact.** It matches the exact channel id plus older
    stored
      spellings of that same id. It no longer groups channels into families, so
      `channel=voice_pipeline` returns only voice-pipeline sessions. Use
      `channelType=voice` for every voice session.
    - Sessions created before this change are not backfilled. They keep the
    coarse
      channel they were stored with (`web_chat`, `voice`, `api`) and report a
      `channelType` only when that channel names one.

    ## Sending parameters in a POST body


    Every GET on this API has a POST form on the same path. Send the same
    parameters

    as a flat JSON object instead of a query string. Use POST when the
    parameters

    themselves must be encrypted: a GET query string is never encrypted. GET
    stays

    available and unchanged.


    - Body keys are exactly the GET query parameter names. Numbers and booleans
    are
      converted to the strings the GET parser expects. List parameters accept a
      JSON array or a comma-separated string.
      `traceDimensions` is an object of dimension name to value, for example
      `{"traceDimensions": {"accountTier": "gold"}}`, instead of the
      `traceDimensions[key]` query form.
    - An unknown key, a `null`, or a nested value is rejected with
      `400 INVALID_QUERY_PARAMETER`. A body that is not a JSON object is rejected
      with `400 INVALID_REQUEST_BODY`.
    - Do not add a query string to a POST (`400 INVALID_QUERY_PARAMETER`), and
    do
      not split parameters between the query string and the body.
    - `Content-Type` must be `application/json` or `application/jose+json`,
      otherwise `415 UNSUPPORTED_MEDIA_TYPE`.
    - Permissions, validation, pagination and the response shape are identical
    to
      the GET form.

    ## Payload encryption


    Payload encryption is an opt-in setting on a Platform Key, configured in
    Studio

    under Settings → API Keys → Platform Keys. It has two independent toggles.

    Neither changes what the key may access, and both are available only to keys

    bound to exactly one project.


    **Request encryption** applies to POST bodies (a GET has no body). The body
    must

    be a JWE (RFC 7516) in flattened JSON serialization, `{protected, iv,

    ciphertext, tag}`, whose protected header is
    `{"alg":"dir","enc":"A256GCM"}`,

    optionally with `kid`, `typ` and `cty`. The key is the 32-byte AES-256
    request

    key Studio shows when request encryption is enabled. `kid` is optional; if
    sent

    it must equal the key's Key ID shown in Studio.


    **Response encryption** applies to every response sent after the key is

    authenticated, successes and errors alike (400, 403, 404, 413, 415, 429,
    500,

    503). The body is a flattened JWE `{protected, encrypted_key, iv,
    ciphertext,

    tag}` with protected header

    `{"alg":"RSA-OAEP-256","enc":"A256GCM","kid":"<Key
    ID>","pkf":"<fingerprint>"}`,

    sealed with a fresh AES-256 key per response that is wrapped with the RSA
    public

    key (≥ 2048 bits) configured on the Platform Key. `pkf` is the SHA-256 hex

    digest of that public key's SubjectPublicKeyInfo DER. The response keeps

    `Content-Type: application/json` and adds `X-ABL-Encrypted: true`.
    Decrypting

    it yields exactly the JSON documented in this spec. A `401` is never
    encrypted

    (the key is not known yet), and a `304` has no body.


    | Key setting | Plain JSON body | JWE body |

    |---|---|---|

    | Request encryption off | accepted | `400 ENCRYPTED_PAYLOAD_INVALID` |

    | Request encryption on | `400 ENCRYPTED_PAYLOAD_INVALID` | decrypted, then
    handled as plain JSON |


    Encryption fails closed: a configured key never receives plaintext by
    accident.


    - `400 ENCRYPTED_PAYLOAD_INVALID` is returned for every envelope problem:
    any
      other `alg`/`enc`, `zip` or `crit`, unknown header parameters, `unprotected`,
      `header`, `aad` or `recipients` members, a `kid` that is not this key's,
      padded or standard base64, a wrong IV (12 bytes) or tag (16 bytes) length, a
      failed authentication tag, or a plaintext that is not JSON.
    - `503 ENCRYPTION_CONFIG_UNAVAILABLE` (with `Retry-After: 30`) means the
    key's
      encryption configuration could not be read. Retry later; there is no
      plaintext fallback.
    - `500 INTERNAL_ERROR` with a content-free body is returned if a response
    cannot
      be encrypted.

    All JWE members are unpadded base64url. The AAD is the ASCII of the
    `protected`

    member, as in standard JWE, so JOSE libraries (for example `jose` for
    Node.js)

    can produce and open these envelopes directly. Pin the algorithms when

    decrypting: key management `RSA-OAEP-256`, content encryption `A256GCM`.
  x-payload-encryption:
    runtime-capability: 'GET /health -> capabilities.payloadEncryption: 2'
servers:
  - url: https://{host}
    description: ABL Runtime public endpoint
    variables:
      host:
        default: runtime.example.com
security:
  - ApiKeyAuth: []
tags:
  - name: Sessions
paths:
  /api/public/analytics/projects/{projectId}/sessions:
    post:
      tags:
        - Sessions
      summary: List session summaries (parameters in the body)
      description: >
        POST form of `GET` on this path. It accepts the same parameters as a
        flat JSON

        body (`SessionsQueryBody`) instead of a query string, and returns the
        same response.

        Use it when the request parameters must be encrypted. See "Sending
        parameters

        in a POST body" and "Payload encryption" in the API description.


        - Request encryption off: send `SessionsQueryBody` as
        `application/json`.

        - Request encryption on: send the same object encrypted as an
          `EncryptedRequest`, preferably as `application/jose+json`.
        - Response encryption on: every response except `401` is an
          `EncryptedResponse` with `X-ABL-Encrypted: true`.
      operationId: queryPublicAnalyticsSessions
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/SessionsQueryBody'
                - $ref: '#/components/schemas/EncryptedRequest'
            examples:
              plain:
                summary: Request encryption off
                value:
                  fromDate: '2026-08-01T00:00:00.000Z'
                  toDate: '2026-08-02T00:00:00.000Z'
                  channel:
                    - web_chat
                    - voice
                  status: ended
                  traceDimensions:
                    accountTier: gold
                  limit: 100
                  offset: 0
              encrypted:
                summary: Request encryption on (JWE of the plain example)
                value:
                  protected: >-
                    eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2In0
                  iv: 0OY1044i46ybmWVI
                  ciphertext: >-
                    tOzaN8ZP3whRATZas7XHZ5ikKXIUe2L-BSKug6PSMx1jACjD3aFbQ8OoykuQ0vVPv9yp8ZQX5-Y76lGmokHYr7BX-CyvoRUCrU8IhwOol7PVaY1Mwyn2uohsmgmnCWlDIftYMDF1o_sOkb9W5xCa79HMVzhMMfoNOwjG8sCiWezNwO8YwJO0zxW_FwW4MEY59CU8IjOqxJX8OuFeaqIIASbZa_meRjtClZQHLA6nG0AbQpTqn6fowzuWgcGyD2WzxlPgR-pNoINMBw
                  tag: Vwm1cqhQtv9TwRIkryoTPQ
          application/jose+json:
            schema:
              $ref: '#/components/schemas/EncryptedRequest'
            example:
              protected: >-
                eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2In0
              iv: 0OY1044i46ybmWVI
              ciphertext: >-
                tOzaN8ZP3whRATZas7XHZ5ikKXIUe2L-BSKug6PSMx1jACjD3aFbQ8OoykuQ0vVPv9yp8ZQX5-Y76lGmokHYr7BX-CyvoRUCrU8IhwOol7PVaY1Mwyn2uohsmgmnCWlDIftYMDF1o_sOkb9W5xCa79HMVzhMMfoNOwjG8sCiWezNwO8YwJO0zxW_FwW4MEY59CU8IjOqxJX8OuFeaqIIASbZa_meRjtClZQHLA6nG0AbQpTqn6fowzuWgcGyD2WzxlPgR-pNoINMBw
              tag: Vwm1cqhQtv9TwRIkryoTPQ
      responses:
        '200':
          description: Session page returned successfully (same body as the GET form).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SessionListResponse'
                  - $ref: '#/components/schemas/EncryptedResponse'
              examples:
                encrypted:
                  summary: >-
                    Response for a key with response encryption on (decrypt to
                    get the plain body)
                  value:
                    protected: >-
                      eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2IiwicGtmIjoiMzg4OTYxNmY1MGNmNTkxZWViZjEwM2FmYmJkNDYxMGQ5MGRjNzg4NjJlMTU2NDE5YzU2NTBkMDRjYWZiNjE5YyJ9
                    encrypted_key: >-
                      TRVuJG7BSHwO9xRyWhDMXhdo7M8G3PZrfZMX2T-wLcCyvGBq3NGq6DNAFMKOPc8onZUYa5LzFvdMcWKMRTSKaG8Q4i_ZIZ6mdOyWvydWZwVotU3Mq7XAYLh7ixQSol3LnfYP2toYxJHHb-ffglOjCe1fayqkEIo81e2UnsG9ITQ6915c4jLna2qcy6qif0ZVkVzOkpesAsY3uUYlgl0FL4vZbealhm_LLSF-usycSCScq5xYEMm1GNvfG3NyP0BzSV4dYCk2FB-2xSqbqePz2OSzby5IV6-aXLqKsull4BNpMZC1HocKbxk1gE4k6dO-E0Qr2ZIGR0M68nIxY-z_Ug
                    iv: 5yEXvNfHRftJ7b6T
                    ciphertext: mwqoUeYNW7bSlBMarz09bA
                    tag: q5cwgh7N4OEJYl5pJ6ydyA
          headers:
            X-ABL-Encrypted:
              $ref: '#/components/headers/XAblEncrypted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/ResponseTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      description: Project identifier bound to the API key.
      schema:
        type: string
        minLength: 1
  schemas:
    SessionsQueryBody:
      type: object
      additionalProperties: false
      description: >
        POST form of the GET query parameters: a flat JSON object whose keys are
        the

        GET query parameter names. For a Platform Key with request encryption
        on, send

        this object encrypted as an `EncryptedRequest` instead.
      properties:
        fromDate:
          description: Same as the `fromDate` query parameter of the GET operation.
          type: string
          format: date-time
        toDate:
          description: Same as the `toDate` query parameter of the GET operation.
          type: string
          format: date-time
        sessionIds:
          description: >-
            Same as the `sessionIds` query parameter of the GET operation. Send
            a JSON array, or a comma-separated string as in the query string.
          anyOf:
            - type: array
              maxItems: 10000
              uniqueItems: true
              items:
                type: string
                minLength: 1
            - type: string
              minLength: 1
        containmentType:
          description: >-
            Same as the `containmentType` query parameter of the GET operation.
            Send a JSON array, or a comma-separated string as in the query
            string.
          anyOf:
            - type: array
              maxItems: 100
              uniqueItems: true
              items:
                type: string
                enum:
                  - contained
                  - contained_resolved
                  - contained_partial
                  - contained_unresolved
                  - escalated
                  - abandoned
                  - failed
            - type: string
              minLength: 1
        environment:
          description: >-
            Same as the `environment` query parameter of the GET operation. Send
            a JSON array, or a comma-separated string as in the query string.
          anyOf:
            - type: array
              maxItems: 4
              uniqueItems: true
              items:
                type: string
                maxLength: 128
                enum:
                  - dev
                  - staging
                  - production
                  - working-copy
            - type: string
              minLength: 1
        callerNumber:
          description: >
            Same as the `callerNumber` query parameter of the GET operation.
            Send a JSON

            array of caller values in any provider format (no URL encoding
            needed), or a

            comma-separated string. Every entry must be a string with at least
            one letter

            or digit and at most 512 characters; an empty array returns 400.
          example:
            - +91 98765 43210
            - Anonymous
          anyOf:
            - type: array
              minItems: 1
              maxItems: 100
              items:
                type: string
                minLength: 1
                maxLength: 512
            - type: string
              minLength: 1
        channelUId:
          description: >-
            Same as the `channelUId` query parameter of the GET operation. Send
            a JSON array, or a comma-separated string as in the query string.
            Each array entry is one value and is never split on commas.
          anyOf:
            - type: array
              maxItems: 100
              uniqueItems: true
              items:
                type: string
                minLength: 1
            - type: string
              minLength: 1
        channel:
          description: >-
            Same as the `channel` query parameter of the GET operation. Send a
            JSON array, or a comma-separated string as in the query string.
          anyOf:
            - type: array
              maxItems: 50
              uniqueItems: true
              items:
                type: string
                maxLength: 128
                enum:
                  - 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
            - type: string
              minLength: 1
        source:
          description: >-
            Same as the `source` query parameter of the GET operation (default
            `user_initiated`). Send a string, a JSON array, or a comma-separated
            string. `production` is the legacy name of `user_initiated` and is
            still accepted.
          anyOf:
            - type: array
              maxItems: 100
              uniqueItems: true
              items:
                type: string
                enum:
                  - user_initiated
                  - workflow
                  - eval
                  - synthetic
                  - debug
                  - demo_insights
                  - production
                  - all
            - type: string
          example:
            - user_initiated
            - workflow
        channelType:
          description: >-
            Same as the `channelType` query parameter of the GET operation. Send
            a string, a JSON array, or a comma-separated string.
          anyOf:
            - type: array
              maxItems: 6
              uniqueItems: true
              items:
                type: string
                enum:
                  - messaging
                  - voice
                  - sdk
                  - webhook
                  - protocol
                  - workflow
            - type: string
              minLength: 1
          example:
            - voice
            - messaging
        traceDimensions:
          type: object
          description: >
            Same filter as the `traceDimensions[key]` query parameter, as an
            object of

            dimension name to value. Values may be strings, numbers, booleans,
            or an array

            of those. Nested objects are rejected.
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: boolean
              - type: array
                items:
                  type:
                    - string
                    - number
                    - boolean
        status:
          description: Same as the `status` query parameter of the GET operation.
          type: string
          enum:
            - active
            - idle
            - ended
            - completed
            - escalated
            - abandoned
            - archived
        dispositionCode:
          description: Same as the `dispositionCode` query parameter of the GET operation.
          type: string
          maxLength: 200
        limit:
          description: Same as the `limit` query parameter of the GET operation.
          type: integer
          minimum: 1
          maximum: 10000
          default: 100
        offset:
          description: Same as the `offset` query parameter of the GET operation.
          type: integer
          minimum: 0
          default: 0
    EncryptedRequest:
      type: object
      additionalProperties: false
      required:
        - protected
        - iv
        - ciphertext
        - tag
      description: >
        Request body for a Platform Key with request encryption on: a JWE in
        flattened

        JSON serialization (RFC 7516 §7.2.2). The plaintext is the JSON body
        documented

        for the plain POST form. Send with `Content-Type: application/jose+json`
        or

        `application/json`.
      properties:
        protected:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: >
            base64url of the protected header JSON. Decodes to
            `RequestProtectedHeader`.

            Its ASCII is also the AES-GCM additional authenticated data.
        encrypted_key:
          type: string
          maxLength: 0
          description: 'Empty or omitted: `dir` has no wrapped key.'
        iv:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of a fresh random 12-byte AES-GCM IV.
        ciphertext:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the AES-256-GCM ciphertext.
        tag:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the 16-byte AES-GCM authentication tag.
    SessionListResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - sessions
        - total
        - offset
        - limit
        - hasMore
      properties:
        success:
          type: boolean
          const: true
          description: |
            Always true on a successful response.
        sessions:
          description: The sessions on this page.
          type: array
          items:
            $ref: '#/components/schemas/Session'
        total:
          type: integer
          minimum: 0
          description: |
            Total number of sessions matching your filters, across all pages.
        offset:
          type: integer
          minimum: 0
          description: |
            The offset applied to this response.
        limit:
          type: integer
          minimum: 1
          maximum: 10000
          description: |
            The page size applied to this response.
        hasMore:
          type: boolean
          description: |
            Whether more pages are available after this one.
    EncryptedResponse:
      type: object
      additionalProperties: false
      required:
        - protected
        - encrypted_key
        - iv
        - ciphertext
        - tag
      description: >
        Response body for a Platform Key with response encryption on (signalled
        by the

        `X-ABL-Encrypted: true` header): a JWE in flattened JSON serialization.
        The

        decrypted plaintext is the JSON body documented for that status code.
      properties:
        protected:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: >-
            base64url of the protected header. Decodes to
            `ResponseProtectedHeader`.
        encrypted_key:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: >-
            The per-response AES-256 key, wrapped with the customer's RSA public
            key using RSA-OAEP-256.
        iv:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the 12-byte AES-GCM IV (fresh per response).
        ciphertext:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the AES-256-GCM ciphertext.
        tag:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the 16-byte AES-GCM authentication tag.
    Session:
      type: object
      additionalProperties: false
      required:
        - id
        - channel
        - source
        - channelType
        - environment
        - status
        - containmentType
        - dispositionCode
        - createdAt
        - lastActivityAt
        - endedAt
        - messageCount
        - traceEventCount
        - tokenCount
        - traceDimensions
        - estimatedCost
        - durationMs
        - idleDurationMs
        - isTest
        - voice
        - contactCenter
      properties:
        id:
          type: string
          description: >
            The session identifier. Use it with the conversation-history and
            traces endpoints.
        channel:
          type: string
          description: >
            The channel the session entered through, exactly as recorded: the
            precise

            channel id (for example `slack`, `voice_pipeline`, `sdk_web`,
            `direct_api`)

            for sessions created from release 1.10.0 on, and the coarse value
            older sessions

            were stored with (for example `web_chat`, `voice`, `api`). Empty
            when no

            channel was recorded. Not restricted to the listed values: a channel
            added

            later is returned as stored.
          examples:
            - slack
            - voice_pipeline
            - sdk_web
            - web_chat
            - ''
        source:
          type: string
          description: >
            Why the session exists. Sessions stored with the older value
            `production`

            or with no Source are reported as `user_initiated`. Clients should
            accept

            values added later.
          enum:
            - user_initiated
            - workflow
            - eval
            - synthetic
            - debug
            - demo_insights
        channelType:
          type:
            - string
            - 'null'
          description: >
            The type of the channel the session entered through. For a session
            stored

            before Channel Type existed it is the type its channel names, and
            `null`

            when the channel names none (`web_chat`, `api`) or no channel was
            recorded.

            An evaluation run (`eval_simulation`) reports the type of what it

            simulates.
          enum:
            - messaging
            - voice
            - sdk
            - webhook
            - protocol
            - workflow
            - null
        environment:
          type: string
          description: Empty when the source column is null.
          enum:
            - ''
            - development
            - staging
            - production
            - working-copy
        status:
          type: string
          description: >
            The session's state. `failed` can appear here even though it cannot
            be used

            as a `status` filter value. Empty when no status was recorded.
          enum:
            - ''
            - active
            - idle
            - ended
            - completed
            - failed
            - escalated
            - abandoned
            - archived
        containmentType:
          description: >
            How the session was resolved — whether the agent handled it or it
            went to a human.
          type: string
          enum:
            - contained
            - contained_resolved
            - contained_partial
            - contained_unresolved
            - escalated
            - abandoned
            - failed
        channelUId:
          type:
            - string
            - 'null'
          description: >
            The end user's channel identifier, normalized (lowercased email,
            E.164

            phone, SIP URI or the provider's user id), for example
            `priya@example.com`

            or `+14155550100`. Null when the channel supplied no end-user
            identity or

            the session was created before this field existed. This is personal
            data.

            Masking is planned for a later release, together with role-based
            access to unmasked values.
        dispositionCode:
          type:
            - string
            - 'null'
          description: >
            The wrap-up code the human agent chose in after-contact work (ACW)
            after a

            transfer to a contact centre, such as `Resolved`, exactly as the
            contact

            centre sent it. Taken from the latest completed ACW of the session
            that

            carried a code.


            `null` when the session was not transferred, the contact centre sent
            no

            code, or ACW completed after the session had already ended. Not the
            same

            thing as `containmentType`, which is the platform's own
            classification.
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: |
            When the session started.
        lastActivityAt:
          type:
            - string
            - 'null'
          format: date-time
          description: |
            When the last message or event occurred in the session.
        endedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: |
            When the session ended. Null while it is still open.
        messageCount:
          $ref: '#/components/schemas/MessageCount'
        traceEventCount:
          $ref: '#/components/schemas/TraceEventCount'
        tokenCount:
          $ref: '#/components/schemas/TokenCount'
        traceDimensions:
          description: |
            Custom dimensions recorded against the session, as key/value pairs.
            Filter on these with the traceDimensions[key] parameter.
          type: object
          additionalProperties:
            type: string
        estimatedCost:
          type: number
          minimum: 0
          description: Estimated cost in the platform billing currency.
        durationMs:
          type: number
          minimum: 0
          description: |
            Total elapsed time from start to end, in milliseconds.
        idleDurationMs:
          type: number
          minimum: 0
          description: >
            Part of the duration where nothing happened — time spent waiting, in
            milliseconds.

            Useful for separating real handling time from waiting.
        isTest:
          type:
            - boolean
            - 'null'
          description: Reserved field; currently returned as null.
        voice:
          description: >
            Call quality of a voice session, one value for each Voice Analytics
            dashboard

            card. `null` when the session was not a voice call, or ended before
            this

            release. A metric the call did not measure is `null`, never `0`.
          oneOf:
            - $ref: '#/components/schemas/SessionVoice'
            - type: 'null'
        contactCenter:
          type: 'null'
          description: >
            Reserved for the queue, agent, wait time, handle time and outcome
            after a

            transfer to Kore Contact Center. Always `null` in this release. The
            key is

            always present.
    ErrorEnvelope:
      type: object
      required:
        - error
      properties:
        success:
          type: boolean
          const: false
          description: |
            Always false on an error response.
        error:
          description: >
            Details of what went wrong. `code` is a stable machine-readable
            value; `message` is

            human-readable.
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        message:
          type: string
          description: >-
            Present on some authorization denials in addition to
            `error.message`.
        required:
          description: >-
            Permission(s) the caller was missing. Present on authorization
            denials.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
    MessageCount:
      type: object
      additionalProperties: false
      required:
        - user
        - agent
        - total
      properties:
        user:
          type: number
          minimum: 0
          description: |
            Messages sent by the end user.
        agent:
          type: number
          minimum: 0
          description: |
            Messages sent by the agent.
        total:
          type: number
          minimum: 0
          description: |
            Total number of trace events recorded for the session.
    TraceEventCount:
      type: object
      additionalProperties: false
      required:
        - llm_call
        - decision
        - tool_call
        - error
        - total
      properties:
        llm_call:
          type: number
          minimum: 0
          description: |
            Number of LLM calls made during the session.
        decision:
          type: number
          minimum: 0
          description: |
            Number of agent decisions taken, such as routing choices.
        tool_call:
          type: number
          minimum: 0
          description: |
            Number of tool calls made.
        error:
          type: number
          minimum: 0
          description: |
            Number of failed events during the session.
        total:
          type: number
          minimum: 0
          description: |
            Total number of trace events recorded for the session.
    TokenCount:
      type: object
      additionalProperties: false
      required:
        - inputTokens
        - cachedTokens
        - cacheWriteTokens
        - completionTokens
        - reasoningTokens
        - outputTokens
        - totalTokens
      properties:
        inputTokens:
          type: number
          minimum: 0
          description: |
            Tokens in the prompts sent to models across the session.
        cachedTokens:
          type: number
          minimum: 0
          description: >
            Input tokens served from the provider prompt cache. Part of
            inputTokens, and usually

            cheaper.
        cacheWriteTokens:
          type:
            - number
            - 'null'
          minimum: 0
          description: >
            Input tokens written to the provider prompt cache across the
            session's LLM calls. Part

            of inputTokens. null means no call in the session reported cache
            writes (or the

            per-call accounting could not be read); 0 means the provider
            reported zero.
        completionTokens:
          type: number
          minimum: 0
          description: |
            Tokens generated as answers, not counting reasoning tokens.
        reasoningTokens:
          type: number
          minimum: 0
          description: >
            Tokens spent on internal model reasoning. Billed as output but not
            part of any visible

            answer.
        outputTokens:
          type: number
          minimum: 0
          description: |
            All tokens produced by models — answers plus reasoning.
        totalTokens:
          type: number
          minimum: 0
          description: |
            Input plus output tokens for the whole session.
    SessionVoice:
      type: object
      additionalProperties: false
      required:
        - mos
        - asrScore
        - e2eLatencyMs
        - bargeInRate
        - dtmfFallbackRate
        - ttsMos
        - silencePercent
      properties:
        mos:
          type:
            - number
            - 'null'
          minimum: 1
          maximum: 5
          description: Inbound network MOS of the call (the Avg MOS card).
        asrScore:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 100
          description: Overall speech-recognition quality score (the ASR Quality card).
        e2eLatencyMs:
          type:
            - number
            - 'null'
          minimum: 0
          description: >
            Average end-to-end response latency in milliseconds (the E2E Latency
            card).

            `null` when no turn was measured.
        bargeInRate:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
          description: >
            Share of turns where the caller interrupted the agent, as a decimal:
            `0.2`

            means 20% (the dashboard card divided by 100). `null` when the call
            had no turns.
        dtmfFallbackRate:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 1
          description: >
            Share of turns answered with the keypad, as a decimal (the dashboard
            card

            divided by 100). `null` when the call had no turns.
        ttsMos:
          type:
            - number
            - 'null'
          minimum: 1
          maximum: 5
          description: Estimated text-to-speech quality (the TTS Quality card).
        silencePercent:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 100
          description: Percent of the call with no speech (the Silence card).
  headers:
    XAblEncrypted:
      description: >-
        Present with value `true` when the body is an `EncryptedResponse`.
        Absent otherwise.
      schema:
        type: string
        enum:
          - 'true'
  responses:
    BadRequest:
      description: >
        Invalid or unsupported filters, pagination, date range, or
        required-filter

        combination.


        Encryption and POST-body errors also return 400:
        `ENCRYPTED_PAYLOAD_INVALID`

        (malformed, unexpected or undecryptable JWE, or a plain body for a

        request-encrypted key), `INVALID_REQUEST_BODY` (POST body is not a JSON
        object),

        and `INVALID_QUERY_PARAMETER` (unknown, null or nested POST body key, or
        a query

        string on a POST).


        `INVALID_CALLER_NUMBER`: the `callerNumber` parameter is present but an
        entry is

        empty or has no letter or digit after cleanup (an empty value, only
        separators,

        a trailing or doubled comma, only whitespace, invisible characters or

        punctuation such as `+`, or an empty POST array), is not a string, or is
        longer

        than 512 characters. Any caller format, including bare

        digits and national formats, is accepted. The message names the position
        of

        the offending entry and never echoes it.


        `INVALID_DISPOSITION_CODE`: the `dispositionCode` parameter is longer
        than 200

        characters after trimming.


        `INVALID_SOURCE`: a `source` value is not one of `user_initiated`,
        `workflow`,

        `eval`, `synthetic`, `debug`, `demo_insights`, `all` (or the older

        `production`), or `all` is combined with another value. The message
        lists the

        allowed values.


        `INVALID_CHANNEL_TYPE`: a `channelType` value is not one of `messaging`,

        `voice`, `sdk`, `webhook`, `protocol`, `workflow`. The message lists the

        allowed values.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    Unauthorized:
      description: Missing or invalid `x-api-key`, or an Authorization header was supplied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: >
        The key lacks `session:read` for its bound project, or
        (`CALLER_NUMBER_LOOKUP_DISABLED`)

        the request used `callerNumber` while the project's reporting exposure
        config

        disables the `identity` field group.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    NotFound:
      description: >-
        Project not found or deliberately concealed because it is outside the
        key's project scope.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    ResponseTooLarge:
      description: A single session cannot fit within the 1 MiB response budget.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    UnsupportedMediaType:
      description: >-
        A POST body was sent with a `Content-Type` other than `application/json`
        or `application/jose+json` (`UNSUPPORTED_MEDIA_TYPE`).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    RateLimited:
      description: Tenant request rate limit exceeded.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    InternalError:
      description: >
        Unexpected query failure.


        Also returned, with a content-free body, when a response cannot be
        encrypted for

        a response-encrypted key.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    Unavailable:
      description: >
        Analytics backing store unavailable.


        `ENCRYPTION_CONFIG_UNAVAILABLE` (with `Retry-After: 30`) means the
        Platform

        Key's payload-encryption configuration could not be read. There is no
        plaintext

        fallback.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Project-bound API key. Do not send an Authorization header with this
        API.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.