> For the complete documentation index, see [llms.txt](https://docs.cekat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cekat.ai/api-documentation/chat/conversation/list-conversations.md).

# List conversations

Lists conversations, most recently active first, with the contact, handling agent, labels, and first and last messages.

This list uses cursor pagination. To get the next page, send `metadata.next_cursor.cursor_id` and `metadata.next_cursor.cursor_ts` from the previous response. Stop when `data` is empty.

```json
{"openapi":"3.0.3","info":{"title":"Cekat Open API","version":"1.0.0"},"tags":[{"name":"Conversation","description":"A conversation is the chat thread between one contact and one of your inboxes. Use these endpoints to list conversations, read one in detail, see which human agent handled each one, and change the AI agent that replies."}],"servers":[{"url":"https://api.cekat.ai","description":"Production"}],"security":[{"CekatApiKey":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"CekatApiKey":{"type":"apiKey","in":"header","name":"api_key","description":"Your business's Cekat API key, from **Settings → Developers & API** in the Cekat dashboard (https://chat.cekat.ai/developers?section=apikeys). Available on the Business and Enterprise plans."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same Cekat API key, sent as `Authorization: Bearer YOUR_API_KEY`. Accepted only by endpoints under `/api/...`."}},"parameters":{"StartDate":{"name":"start_date","in":"query","required":false,"description":"Only include items created on or after this date (`YYYY-MM-DD`). Cannot be combined with `start_datetime`.","schema":{"type":"string","format":"date"}},"EndDate":{"name":"end_date","in":"query","required":false,"description":"Only include items created on or before the end of this date (`YYYY-MM-DD`). Cannot be combined with `end_datetime`.","schema":{"type":"string","format":"date"}},"StartDatetime":{"name":"start_datetime","in":"query","required":false,"description":"Only include items created at or after this time (`YYYY-MM-DDTHH:mm:ss`, optional offset such as `+07:00` or `Z`). Cannot be combined with `start_date`.","schema":{"type":"string"}},"EndDatetime":{"name":"end_datetime","in":"query","required":false,"description":"Only include items created at or before this time (`YYYY-MM-DDTHH:mm:ss`, optional offset). Cannot be combined with `end_date`.","schema":{"type":"string"}},"UserTimezone":{"name":"X-User-Timezone","in":"header","required":false,"description":"IANA time zone used to read date filters that have no offset. Defaults to `Asia/Jakarta`.","schema":{"type":"string"}}},"schemas":{"ConversationListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"stage_status":{"type":"string","enum":["open","pending","assigned","resolved"]},"inbox_id":{"type":"string","format":"uuid"},"inbox_name":{"type":"string"},"platform_type":{"type":"string"},"contact_id":{"type":"string","format":"uuid"},"contact_name":{"type":"string"},"contact_phone":{"type":"string","nullable":true},"contact_platform_id":{"type":"string","nullable":true},"contact_username":{"type":"string","nullable":true},"handled_by_id":{"type":"string","format":"uuid","nullable":true,"description":"The human agent handling the conversation."},"handled_by_name":{"type":"string","nullable":true},"resolved_at":{"type":"string","format":"date-time","nullable":true},"resolved_by_id":{"type":"string","format":"uuid","nullable":true},"resolved_by_name":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true,"description":"The contact's notes."},"additional_data":{"type":"object","nullable":true,"additionalProperties":true},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"first_message":{"type":"object","properties":{"message":{"type":"string"}}},"last_message":{"$ref":"#/components/schemas/MessageSnippet"}}},"MessageSnippet":{"type":"object","properties":{"message":{"type":"string"},"created_at":{"type":"string","format":"date-time","nullable":true}}},"ApiError":{"type":"object","description":"Error body returned by the `/api/...` endpoints.","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"statusCode":{"type":"integer"},"error":{"type":"object","properties":{"message":{"type":"string"}}},"correlationId":{"type":"string","description":"Request ID. Include it when contacting Cekat support."}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"ApiUnauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Wait and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/api/conversations":{"get":{"tags":["Conversation"],"operationId":"ListConversations","summary":"List conversations","description":"Lists conversations, most recently active first, with the contact, handling agent, labels, and first and last messages.\n\nThis list uses cursor pagination. To get the next page, send `metadata.next_cursor.cursor_id` and `metadata.next_cursor.cursor_ts` from the previous response. Stop when `data` is empty.\n","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor_id","in":"query","required":false,"description":"`next_cursor.cursor_id` from the previous page.","schema":{"type":"string","format":"uuid"}},{"name":"cursor_ts","in":"query","required":false,"description":"`next_cursor.cursor_ts` from the previous page.","schema":{"type":"string"}},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/StartDatetime"},{"$ref":"#/components/parameters/EndDatetime"},{"$ref":"#/components/parameters/UserTimezone"}],"responses":{"200":{"description":"A page of conversations.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ConversationListItem"}},"metadata":{"type":"object","properties":{"next_cursor":{"type":"object","properties":{"cursor_id":{"type":"string","nullable":true},"cursor_ts":{"type":"string","nullable":true}}}}}}}}}},"400":{"description":"A filter is invalid, or `limit` is above 100.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/ApiUnauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```