> ## 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 messages of one of the key's conversations > Return the messages of a conversation that belongs to the authenticated API key, newest first. Only user and assistant messages are returned: tool exchanges, tool-activity rows and the system prompt are never exposed. ## Authentication - **Authorization**: `Bearer cht_live_.`; both `read-only` and `full` keys may read. ## Path Parameters - **agent_id**: The agent the key is bound to - **conversation_id**: A conversation id from the conversations endpoint or a chat response. A conversation of another key or channel, or an unknown id, is `conversation_not_found` ## Query Parameters - **date_from**, **date_to**: ISO-8601 bounds on `created_at`; `date_to` is exclusive; same UTC rules as the conversations endpoint - **limit**: page size, 1-100 (default 20) - **cursor**: the `next_cursor` value from the previous page ## Example Request ```bash curl -X GET "/v1/agents/{agent_id}/conversations/{conversation_id}/messages?limit=50" \ -H "Authorization: Bearer cht_live_{key_id}.{secret}" ``` ## Response - **data**: array of messages, newest first, each with `id`, `role` (`user` or `assistant`), `type` (`text`, `image`, `file`, ...), `content` (text; non-text payloads are rendered as their text or name) and `created_at` - **next_cursor**: opaque string for the next page, or `null` on the last page ## Errors - `invalid_api_key` (401), `agent_mismatch` (403) - `conversation_not_found` (404): not this key's conversation - `validation_error` (422): bad `limit`, dates, or a malformed `cursor` - `rate_limit_exceeded` (429), `api_rate_limit_unavailable` (503), `internal_error` (500) ## OpenAPI ````yaml /openapi.json get /v1/agents/{agent_id}/conversations/{conversation_id}/messages 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/{conversation_id}/messages: get: tags: - Public API summary: List the messages of one of the key's conversations description: >- Return the messages of a conversation that belongs to the authenticated API key, newest first. Only user and assistant messages are returned: tool exchanges, tool-activity rows and the system prompt are never exposed. ## Authentication - **Authorization**: `Bearer cht_live_.`; both `read-only` and `full` keys may read. ## Path Parameters - **agent_id**: The agent the key is bound to - **conversation_id**: A conversation id from the conversations endpoint or a chat response. A conversation of another key or channel, or an unknown id, is `conversation_not_found` ## Query Parameters - **date_from**, **date_to**: ISO-8601 bounds on `created_at`; `date_to` is exclusive; same UTC rules as the conversations endpoint - **limit**: page size, 1-100 (default 20) - **cursor**: the `next_cursor` value from the previous page ## Example Request ```bash curl -X GET "/v1/agents/{agent_id}/conversations/{conversation_id}/messages?limit=50" \ -H "Authorization: Bearer cht_live_{key_id}.{secret}" ``` ## Response - **data**: array of messages, newest first, each with `id`, `role` (`user` or `assistant`), `type` (`text`, `image`, `file`, ...), `content` (text; non-text payloads are rendered as their text or name) and `created_at` - **next_cursor**: opaque string for the next page, or `null` on the last page ## Errors - `invalid_api_key` (401), `agent_mismatch` (403) - `conversation_not_found` (404): not this key's conversation - `validation_error` (422): bad `limit`, dates, or a malformed `cursor` - `rate_limit_exceeded` (429), `api_rate_limit_unavailable` (503), `internal_error` (500) operationId: >- list_messages_v1_agents__agent_id__conversations__conversation_id__messages_get parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id - name: conversation_id in: path required: true schema: type: string title: Conversation 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 conversation's messages plus the next cursor content: application/json: schema: $ref: '#/components/schemas/ApiMessageListResponse' '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' '404': description: conversation_not_found 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: ApiMessageListResponse: properties: data: items: $ref: '#/components/schemas/ApiMessageItem' 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: ApiMessageListResponse ApiErrorResponse: properties: error: $ref: '#/components/schemas/ApiErrorDetail' type: object required: - error title: ApiErrorResponse description: The one envelope every public API failure answers with. ApiMessageItem: properties: id: type: string title: Id role: type: string enum: - user - assistant title: Role type: type: string title: Type content: type: string title: Content description: Message text; non-text payloads are rendered as text created_at: type: string format: date-time title: Created At type: object required: - id - role - type - content - created_at title: ApiMessageItem 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 ````