> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatnorris.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List conversations

> Get the paginated list of your organization's conversations.

# List conversations

Returns all of the organization's conversations, sorted by latest activity in descending order by default. You can filter by status or by agent, and change the sort criterion. Playground test conversations aren't included.

```http theme={null}
GET https://app.chatnorris.ai/api/v2/conversations
Authorization: Bearer <your_api_key>
```

**Required scope:** `conversations:read`

***

## Query parameters

| Parameter | Type | Description |
| - | - | - |
| `status` | string | Filter by status: `bot`, `handoff`, `open` or `closed` |
| `chatbot_id` | string | Filter by agent |
| `created_after` | string | Only conversations created after this date (ISO 8601, e.g. `2026-09-01T00:00:00Z`) |
| `order_by` | string | Sort field: `created_at` or `updated_at`. Default: `updated_at` |
| `page` | integer | Page number. Default: `1` |
| `per_page` | integer | Results per page. Default: `25`, maximum `100` |

***

## Response

```json theme={null}
{
  "status": "success",
  "data": {
    "conversations": [
      {
        "id": "conv_abc123",
        "chatbot_id": "bot_xyz789",
        "visitor_id": "visitor_001",
        "visitor_name": "Juan Pérez",
        "visitor_email": "juan@empresa.com",
        "status": "closed",
        "channel": "web",
        "created_at": "2026-06-28T14:00:00.000Z",
        "updated_at": "2026-06-28T14:35:00.000Z"
      }
    ]
  },
  "pages": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 25,
    "total": 240
  }
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique ID of the conversation |
| `chatbot_id` | string | ID of the agent that handled the conversation |
| `visitor_id` | string | Visitor identifier (generated automatically) |
| `visitor_name` | string \| null | Visitor's name (if captured, for example with the Lead Form) |
| `visitor_email` | string \| null | Visitor's email (if captured) |
| `status` | string | Status: `bot` (in progress), `handoff` (waiting for an agent), `open` (being handled), `closed` |
| `channel` | string | Channel: `web`, `whatsapp`, `instagram`, `telegram`, `messenger`, `email` or `api` (conversations created with the API) |
| `created_at` | string | Start date (ISO 8601) |
| `updated_at` | string | Latest activity (ISO 8601) |

> [!TIP]
>
> To do incremental polling (for example, to sync new conversations to another system), combine `created_after` with `order_by=created_at` and save the `created_at` of the last result as the starting point for the next query.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.