# List conversations

Source: https://docs.vlayers.ai/reference/conversations/list-conversations

`GET /v1/conversations` · scope `messages:read`

Returns the conversations in your workspace, most recently active first. Filter by channel, sender or controller — for example `controller=human` lists the conversations waiting for a person.

Requires an API key with the `messages:read` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `channel` | query | string | no | Only conversations on this channel. Example: `"whatsapp"` |
| `bindingId` | query | string | no | Only conversations on this sender (a connected WhatsApp, Telegram or Discord account). Example: `"0192f5a9-2b3c-7d4e-9f5a-6b7c8d9e0f12"` |
| `controller` | query | "agent" \| "api" \| "human" | no | Only conversations answered by `agent`, `api` (your code) or `human`. Example: `"human"` |
| `updatedAfter` | query | string | no | Only conversations with activity after this time (ISO 8601). Example: `"2026-10-20T00:00:00.000Z"` |
| `cursor` | query | string | no | The previous page's `nextCursor`. Example: `"eyJ1IjoiMjAyNi0xMC0yMFQxNTowNDowNVoifQ"` |
| `limit` | query | integer | no | How many items to return, 1–100. Default 50. Example: `20` |

## Request

cURL:

```bash
curl "https://api.vlayers.ai/v1/conversations?controller=human&limit=20" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { createVoiceLayerClient, listConversations } from '@voicelayer/api';

const client = createVoiceLayerClient({ apiKey: process.env.VOICELAYER_API_KEY!, throwOnError: true });

const { data } = await listConversations({
  client,
  query: {
    controller: 'human',
    limit: 20
  }
});
console.log(data.conversations);
```

Python:

```python
import os
import voicelayer

config = voicelayer.Configuration(access_token=os.environ["VOICELAYER_API_KEY"])
with voicelayer.ApiClient(config) as client:
    api = voicelayer.ConversationsApi(client)
    result = api.list_conversations(
        controller="human",
        limit=20,
    )
    print(result.conversations)
```

## Response `200`

```json
{
  "conversations": [
    {
      "id": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
      "channel": "sms",
      "lineId": "0192f5a8-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "bindingId": null,
      "peer": {
        "address": "+15550123"
      },
      "controller": "api",
      "status": "open",
      "openedAt": "2026-10-20T15:04:05.000Z",
      "lastActivityAt": "2026-10-20T15:04:05.000Z",
      "test": true
    }
  ],
  "nextCursor": null
}
```