> ## Documentation Index > Fetch the complete documentation index at: https://docs.chattler.ai/llms.txt > Use this file to discover all available pages before exploring further. # List the key's conversations > Return the conversations that belong to the authenticated API key, most recently updated first. Every key has its own isolated namespace: a conversation is identified by the key and the `external_user_id` the client supplied, so the same external user reached through two different keys is two different conversations, and a key never sees dialogs from another key or channel. ## Authentication - **Authorization**: `Bearer cht_live_.` — the only accepted form. Query-string credentials are ignored, and no `Browser-ID` header is needed. - Both `read-only` and `full` keys may call this endpoint. ## Path Parameters - **agent_id**: The agent the key is bound to; a key used against another agent is refused ## Query Parameters - **external_user_id**: only conversations of this external user - **date_from**, **date_to**: ISO-8601 bounds on `updated_at`; `date_to` is exclusive. Timezone-aware values are converted to UTC, naive values are read as UTC, and `date_to` earlier than `date_from` is a validation error - **limit**: page size, 1-100 (default 20) - **cursor**: the `next_cursor` value from the previous page; omit for the first page ## Example Request ```bash curl -X GET "/v1/agents/{agent_id}/conversations?limit=20&date_from=2026-09-01T00:00:00Z" \ -H "Authorization: Bearer cht_live_{key_id}.{secret}" ``` ## Response - **data**: array of conversations, most recently updated first, each with `id`, `external_user_id`, `created_at`, `updated_at` (ISO-8601 UTC) and `last_message_preview` (the latest user or assistant text, truncated to 160 characters, or `null`) - **next_cursor**: opaque string for the next page, or `null` on the last page Every response, success or failure, carries an **X-Request-ID** header (a UUID) and the rate-limit headers **X-RateLimit-Limit**, **X-RateLimit-Remaining**, **X-RateLimit-Reset**. ## Errors All public API errors use one envelope: `{"error": {"code": "...", "message": "...", "request_id": "..."}}`. - `invalid_api_key` (401): missing, malformed, unknown, or wrong-secret key - `agent_mismatch` (403): the key belongs to a different agent - `validation_error` (422): bad `limit` or malformed `cursor` - `rate_limit_exceeded` (429): the key's technical window is exhausted; `Retry-After` says when to retry - `api_rate_limit_unavailable` (503): the limiter backend is down; the request is refused rather than served unmetered, retry after `Retry-After` - `internal_error` (500): unexpected failure; quote the `request_id` when reporting it ## OpenAPI ````yaml /openapi.json get /v1/agents/{agent_id}/conversations openapi: 3.1.0 info: title: Chattler Agent API version: 1.0.0 description: >- Public REST API for talking to a Chattler agent with an API key. Every request runs the agent's ordinary runtime (system prompt, knowledge base, tools, dialog history) and is billed to the owner's balance. servers: - url: https://api.chattler.ai security: - ApiKeyBearer: [] paths: /v1/agents/{agent_id}/conversations: get: tags: - Public API summary: List the key's conversations description: >- Return the conversations that belong to the authenticated API key, most recently updated first. Every key has its own isolated namespace: a conversation is identified by the key and the `external_user_id` the client supplied, so the same external user reached through two different keys is two different conversations, and a key never sees dialogs from another key or channel. ## Authentication - **Authorization**: `Bearer cht_live_.` — the only accepted form. Query-string credentials are ignored, and no `Browser-ID` header is needed. - Both `read-only` and `full` keys may call this endpoint. ## Path Parameters - **agent_id**: The agent the key is bound to; a key used against another agent is refused ## Query Parameters - **external_user_id**: only conversations of this external user - **date_from**, **date_to**: ISO-8601 bounds on `updated_at`; `date_to` is exclusive. Timezone-aware values are converted to UTC, naive values are read as UTC, and `date_to` earlier than `date_from` is a validation error - **limit**: page size, 1-100 (default 20) - **cursor**: the `next_cursor` value from the previous page; omit for the first page ## Example Request ```bash curl -X GET "/v1/agents/{agent_id}/conversations?limit=20&date_from=2026-09-01T00:00:00Z" \ -H "Authorization: Bearer cht_live_{key_id}.{secret}" ``` ## Response - **data**: array of conversations, most recently updated first, each with `id`, `external_user_id`, `created_at`, `updated_at` (ISO-8601 UTC) and `last_message_preview` (the latest user or assistant text, truncated to 160 characters, or `null`) - **next_cursor**: opaque string for the next page, or `null` on the last page Every response, success or failure, carries an **X-Request-ID** header (a UUID) and the rate-limit headers **X-RateLimit-Limit**, **X-RateLimit-Remaining**, **X-RateLimit-Reset**. ## Errors All public API errors use one envelope: `{"error": {"code": "...", "message": "...", "request_id": "..."}}`. - `invalid_api_key` (401): missing, malformed, unknown, or wrong-secret key - `agent_mismatch` (403): the key belongs to a different agent - `validation_error` (422): bad `limit` or malformed `cursor` - `rate_limit_exceeded` (429): the key's technical window is exhausted; `Retry-After` says when to retry - `api_rate_limit_unavailable` (503): the limiter backend is down; the request is refused rather than served unmetered, retry after `Retry-After` - `internal_error` (500): unexpected failure; quote the `request_id` when reporting it operationId: list_conversations_v1_agents__agent_id__conversations_get parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id - name: external_user_id in: query required: false schema: anyOf: - type: string maxLength: 255 - type: 'null' title: External User Id - name: date_from in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Date From - name: date_to in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Date To - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor responses: '200': description: One page of the key's conversations plus the next cursor content: application/json: schema: $ref: '#/components/schemas/ApiConversationListResponse' '401': description: invalid_api_key content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: agent_mismatch or permission_denied content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '422': description: validation_error content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '429': description: rate_limit_exceeded content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '503': description: api_rate_limit_unavailable content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' security: - ApiKeyBearer: [] components: schemas: ApiConversationListResponse: properties: data: items: $ref: '#/components/schemas/ApiConversationItem' type: array title: Data next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Opaque cursor for the next page; null on the last page type: object required: - data title: ApiConversationListResponse ApiErrorResponse: properties: error: $ref: '#/components/schemas/ApiErrorDetail' type: object required: - error title: ApiErrorResponse description: The one envelope every public API failure answers with. ApiConversationItem: properties: id: type: string title: Id description: Conversation id, stable for the key and external user external_user_id: type: string title: External User Id created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At last_message_preview: anyOf: - type: string - type: 'null' title: Last Message Preview description: Text of the latest user or assistant message, truncated type: object required: - id - external_user_id - created_at - updated_at title: ApiConversationItem ApiErrorDetail: properties: code: type: string title: Code description: Stable machine-readable error code message: type: string title: Message description: Human-readable explanation request_id: type: string title: Request Id description: UUID of this request, also in X-Request-ID type: object required: - code - message - request_id title: ApiErrorDetail securitySchemes: ApiKeyBearer: type: http description: 'Agent API key: Authorization: Bearer cht_live_.' scheme: bearer ````