> ## 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

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


Use this endpoint to retrieve the same session-level analytics as the [corresponding GET operation](/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.

For filter details, see the [GET endpoint help article](/agent-platform/api-reference/analytics-list-session-summaries).


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


    ## 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-source-release: develop
  x-source-commit: b6a1a328b3e089e03ca2494a7091d72a6a481d4b
  x-payload-encryption:
    jira: ABLP-5317
    source: develop, PR
    source-commit: 6de86f59eb
    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
            - 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.
          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:
                  - 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
            - type: string
              minLength: 1
        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
        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
        - environment
        - status
        - containmentType
        - createdAt
        - lastActivityAt
        - endedAt
        - messageCount
        - traceEventCount
        - tokenCount
        - traceDimensions
        - estimatedCost
        - durationMs
        - idleDurationMs
        - isTest
      properties:
        id:
          type: string
          description: >
            The session identifier. Use it with the conversation-history and
            traces endpoints.
        channel:
          type: string
          description: >
            The channel the conversation came in on, exactly as recorded — not
            grouped

            into a family the way the `channel` filter is. Empty when no channel
            was

            recorded.
          enum:
            - ''
            - 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
        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
        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.
    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
        - 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.
        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.
  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.
      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.