> ## 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 conversation messages > Messages are ordered by time, then by message ID to keep the order stable. Different filters combine with AND, and multiple values in the same filter combine with OR. A date-range query with no other filter that would span more than 10,000 sessions is rejected with `400`, so narrow the range or add `sessionIds` for busy projects. Returns the messages exchanged in a project's conversations chronologically. Message content is filtered according to the project's PII policy before it is returned, so sensitive values may be masked or removed. Messages are ordered by time, then by message ID to keep the order stable. Different filters combine with AND, and multiple values in the same filter combine with OR. Give either a date range (`fromDate` and `toDate` together) or a list of `sessionIds`. A date-range query with no other filter may span a long list of sessions, so always use a filter and paginate as needed. A response that span more than 10,000 sessions is rejected with `400`, so narrow the range or add `sessionIds` for busy projects. For pagination, prefer `cursor`: pass the `nextCursor` value from the previous response. `offset` also works, and `skip` is an older name for `offset` that is still accepted. Use only one of the three in a single request. Authenticate with the `x-api-key` header. The key must be bound to the project you are querying and have `analytics:read` permission. ## OpenAPI ````yaml agent-platform/api-specs/messages.yaml get /api/public/analytics/projects/{projectId}/conversation-history openapi: 3.1.0 info: title: ABL Public Analytics Messages API version: 1.0.0 summary: Retrieve project-scoped conversation messages. description: > Returns the messages exchanged in a project's conversations, in order. Message content is filtered according to the project's PII policy before it is returned, so sensitive values may be masked or removed. Give either a date range (`fromDate` and `toDate` together) or a list of `sessionIds`. For paging, prefer `cursor`: pass the `nextCursor` value from the previous response. `offset` also works, and `skip` is an older name for `offset` that is still accepted. Use only one of the three in a single request. Authenticate with the `x-api-key` header. The key must be bound to the project you are querying and have `analytics: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":"","pkf":""}`, 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} variables: host: default: runtime.example.com security: - ApiKeyAuth: [] tags: - name: Messages paths: /api/public/analytics/projects/{projectId}/conversation-history: get: tags: - Messages summary: List conversation messages description: > Messages are ordered by time, then by message ID to keep the order stable. Different filters combine with AND, and multiple values in the same filter combine with OR. A date-range query with no other filter that would span more than 10,000 sessions is rejected with `400`, so narrow the range or add `sessionIds` for busy projects. operationId: listPublicAnalyticsMessages parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/FromDate' - $ref: '#/components/parameters/ToDate' - $ref: '#/components/parameters/SessionIds' - name: channelUIds in: query description: > Filter to messages from specific end users, using the identity recorded for them on the channel. Pass up to 100 values, comma-separated or by repeating the parameter. style: form explode: false schema: type: array maxItems: 100 uniqueItems: true items: type: string minLength: 1 - name: callerNumber in: query description: > 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: this endpoint compares the caller value the provider stored on the session record, as received, with the match key, the match key without `+`, and the cleaned value as you sent it. It covers sessions recorded before this filter shipped. Pasting the provider value exactly as stored matches, unless the stored value itself contains invisible characters, fullwidth digits, Unicode dashes or surrounding whitespace (those are cleaned from what you send, so only its E.164 or bare-digit form can match). A re-formatted copy matches here only when it shares the E.164 or bare-digit form of the stored value: for example `+44 20 7946 0958` does not match a stored `+44 (0)20 7946 0958`, and `09876543210` does not match a stored `098765 43210`, although `/sessions` matches both. Playground and Studio debug sessions are never matched. style: form explode: false schema: type: array maxItems: 100 items: type: string minLength: 1 maxLength: 512 - name: channel in: query description: > Filter by the channel the conversation took place on. Pass up to 100 values, comma-separated or by repeating the parameter. Matched exactly as stored, with no alias handling. Unlike the sessions endpoint, `web` and `web_chat` are different values here, and shorthand such as `sms` or `sdk_http` matches nothing — use the exact channel name. Not restricted to a fixed list, so an unrecognised value returns no results rather than an error. style: form explode: false schema: type: array maxItems: 100 uniqueItems: true items: type: string 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 - name: environment in: query description: > Filter by environment. Pass up to 100 values, comma-separated or by repeating the parameter. Matched exactly as stored. Not restricted to a fixed list, so an unrecognised value returns no results rather than an error, though in practice only the four values below are stored. style: form explode: false schema: type: array maxItems: 100 uniqueItems: true items: type: string enum: - dev - staging - production - working-copy - $ref: '#/components/parameters/TraceDimension' - name: cursor in: query description: > Pass the `nextCursor` value from the previous response to get the next page. Do not use together with `offset` or `skip`. schema: type: string minLength: 1 - name: offset in: query description: | Number of messages to skip before the first one returned. Do not use together with `cursor` or `skip`. schema: type: integer minimum: 0 default: 0 - name: skip in: query deprecated: true description: > An older name for `offset`, kept for compatibility. Prefer `offset`. Do not use together with `cursor` or `offset`. schema: type: integer minimum: 0 - name: limit in: query description: > How many messages 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. schema: type: integer minimum: 1 maximum: 10000 default: 100 - name: direction in: query description: | Sort order by time: `asc` for oldest first, `desc` for newest first. schema: type: string enum: - asc - desc default: asc responses: '200': description: Message page returned successfully. headers: Cache-Control: schema: type: string example: private, no-store, max-age=0 X-ABL-Encrypted: $ref: '#/components/headers/XAblEncrypted' content: application/json: schema: oneOf: - $ref: '#/components/schemas/MessageListResponse' - $ref: '#/components/schemas/EncryptedResponse' example: success: true totalRecords: 2 hasMore: false offset: 0 limit: 100 messages: - id: msg-01J4S8Y2 sessionId: sess-01J4S8Y1 type: incoming role: user content: Hello channel: web_chat sourceChannel: web_chat environment: production channelUId: contact-123 traceDimensions: accountTier: gold traceId: trace-123 attachmentIds: [] hasPII: false metadata: clientVersion: 1.4.2 sequence: 1 agentName: null timestamp: '2026-08-05T14:30:00.000Z' createdAt: '2026-08-05T14:30:00.120Z' updatedAt: '2026-08-05T14:30:00.120Z' - id: msg-01J4S8Y3 sessionId: sess-01J4S8Y1 type: outgoing role: assistant content: How can I help? channel: web_chat sourceChannel: web_chat environment: production channelUId: contact-123 traceDimensions: accountTier: gold traceId: trace-124 attachmentIds: [] hasPII: false metadata: isLlmGenerated: true responseProvenance: schemaVersion: 1 kind: llm disclaimerRequired: true usedLlmInternally: true sequence: 2 agentName: Support Agent timestamp: '2026-08-05T14:30:01.000Z' createdAt: '2026-08-05T14:30:01.100Z' updatedAt: '2026-08-05T14:30:01.100Z' nextCursor: null '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' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/Unavailable' components: parameters: ProjectId: name: projectId in: path required: true schema: type: string minLength: 1 FromDate: name: fromDate in: query description: >- Inclusive ISO 8601 timestamp. Required with `toDate` unless `sessionIds` is supplied. schema: type: string format: date-time ToDate: name: toDate in: query description: >- Exclusive ISO 8601 timestamp. Required with `fromDate` unless `sessionIds` is supplied. schema: type: string format: date-time SessionIds: name: sessionIds in: query description: > 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. style: form explode: false schema: type: array maxItems: 10000 uniqueItems: true items: type: string minLength: 1 TraceDimension: name: traceDimensions[key] in: query description: > Filter by a custom dimension recorded against the session. Replace `key` with the dimension name — for example `traceDimensions[tier]=gold`. Repeat with different keys to require all of them. Values match exactly. allowReserved: true schema: type: string x-dynamic-parameter: true headers: XAblEncrypted: description: >- Present with value `true` when the body is an `EncryptedResponse`. Absent otherwise. schema: type: string enum: - 'true' schemas: MessageListResponse: type: object additionalProperties: false required: - success - totalRecords - hasMore - offset - limit - messages - nextCursor properties: success: type: boolean const: true description: | Always true on a successful response. totalRecords: type: integer minimum: 0 description: | Total number of messages matching your filters, across all pages. hasMore: type: boolean description: | Whether more pages are available after this one. 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. messages: type: array items: $ref: '#/components/schemas/Message' description: | The messages on this page. nextCursor: type: - string - 'null' description: Opaque cursor for the next page. 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. Message: type: object additionalProperties: false required: - id - sessionId - type - role - content - channel - sourceChannel - environment - channelUId - traceDimensions - traceId - attachmentIds - hasPII - metadata - sequence - messageOrder - orderingVersion - agentName - timestamp - createdAt - updatedAt properties: id: type: string description: | The message identifier. sessionId: type: string description: | The conversation this message belongs to. type: type: string enum: - incoming - outgoing - system - tool description: > Direction of the message: `incoming` from the end user, `outgoing` to the end user, `system` for platform messages, `tool` for tool output. role: type: string enum: - user - assistant - system - tool description: | Who the message is attributed to, in the usual chat sense. content: type: string description: | The message text, after the project PII policy has been applied. channel: type: string description: Stored session channel, matched exactly by the `channel` filter. 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 sourceChannel: type: string description: > The channel this individual message came in on. This can differ from the session's `channel` if the conversation moved between channels part-way through. 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: description: | The environment the conversation ran in. Null when not recorded. type: - string - 'null' enum: - dev - staging - production - working-copy - null channelUId: type: - string - 'null' description: Resolved end-user identity for the channel session. traceDimensions: type: - object - 'null' additionalProperties: type: string description: | Custom dimensions recorded against the session, as key/value pairs. traceId: type: - string - 'null' description: > The trace covering how this message was produced. Use it with the traces endpoint. attachmentIds: type: array items: type: string description: | Identifiers of any files attached to the message. hasPII: type: boolean description: > Whether personal information was detected in this message. When true, the content you see may be masked. metadata: type: object additionalProperties: true description: >- Sanitized message metadata. Assistant messages include normalized response provenance. properties: isLlmGenerated: type: boolean description: > Whether this message was generated by a model rather than scripted. responseProvenance: $ref: '#/components/schemas/ResponseProvenance' sequence: type: - number - 'null' minimum: 0 description: | Position of the message within its session, starting at 1. messageOrder: type: - number - 'null' description: > Durable ordering position recorded when the message was written. Null for messages stored before durable ordering was recorded. orderingVersion: type: number minimum: 1 description: > Version of the ordering scheme behind `messageOrder`. `1` when no version was recorded. agentName: type: - string - 'null' description: | The agent that produced this message. Null for user messages. timestamp: type: string format: date-time description: | When the message was sent. createdAt: type: string format: date-time description: | When the message record was created. updatedAt: type: string format: date-time description: | When the message record was last changed. 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 ResponseProvenance: type: object additionalProperties: false required: - schemaVersion - kind - disclaimerRequired - usedLlmInternally properties: schemaVersion: type: integer const: 1 description: Version of this provenance metadata contract. kind: type: string enum: - scripted - llm - mixed description: >- `scripted` for authored output, `llm` for model-generated output, or `mixed` when both contributed. disclaimerRequired: type: boolean description: True when the customer-visible response was LLM-generated. usedLlmInternally: type: boolean description: Whether an LLM contributed internally including to scripted final output.: null responses: BadRequest: description: > The request could not be understood. Common causes: an invalid or one-sided date range, neither a date range nor `sessionIds` supplied, more than one of `cursor`, `offset`, and `skip` used together, too many filter values, or a date-range query that would span more than 10,000 sessions. The `error.code` says which. 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 Authorization was supplied. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Forbidden: description: > The key lacks `analytics: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 concealed because it is outside the key's scope. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/EncryptedResponse' ResponseTooLarge: description: A single rendered message cannot fit within the 1 MiB response budget. 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 conversation-history 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: > Conversation-history or trace-dimension 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.