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

# List conversations

> Page through the conversation logs in a workspace: calls, text threads and website widget sessions, newest first.

Read only, on every plan. Deleted conversations are never returned.

<Tip>
  `workspaceId` is required for **account-scoped** API keys and inferred from the key for **workspace-scoped** keys. See [Workspace ID and Request Scope](/authentication#workspace-id-and-request-scope).
</Tip>

<ParamField query="workspaceId" type="string">
  Workspace UUID (required for account API keys, optional for workspace API keys)
</ParamField>

<ParamField query="type" type="string">
  `voice` (phone calls), `chat` (text channels) or `web` (website widget)
</ParamField>

<ParamField query="channel" type="string">
  One of `call`, `sms`, `email`, `whatsapp`, `instagram`, `messenger`, `web_chat`, `web`. A channel that doesn't match `type` returns a `400`. A channel with no conversations returns an empty page.
</ParamField>

<ParamField query="direction" type="string">
  Calls only: `inbound` or `outbound`. Combined with a chat or web `type` or `channel`, it returns a `400`.
</ParamField>

<ParamField query="agentId" type="string">
  Only conversations handled by this agent
</ParamField>

<ParamField query="contactId" type="string">
  Only conversations with this contact
</ParamField>

<ParamField query="status" type="string">
  `open`, `closed` or `snoozed`
</ParamField>

<ParamField query="startDate" type="string">
  ISO 8601 date-time. Conversations created at or after it.
</ParamField>

<ParamField query="endDate" type="string">
  ISO 8601 date-time. Conversations created before it.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Conversations per page, from 1 to 100
</ParamField>

<ParamField query="offset" type="integer" default="0">
  How many conversations to skip, from 0 to 100,000. Add `limit` to `offset` for the next page while `hasMore` is true. To reach older conversations, narrow `startDate` and `endDate`.
</ParamField>

## Channels

| Channel | Type | What it is |
| - | - | - |
| `call` | `voice` | A phone call |
| `sms` | `chat` | A text message thread |
| `email` | `chat` | An email thread |
| `whatsapp` | `chat` | A WhatsApp thread |
| `instagram` | `chat` | An Instagram direct message thread |
| `messenger` | `chat` | A Facebook Messenger thread |
| `web_chat` | `chat` | A text thread that is not tied to any of the channels above |
| `web` | `web` | A session in the website widget |

## Outcome

`outcome` is one of `appointment_booked`, `transferred`, `follow_up`, `callback_requested`, `not_interested`, `wrong_number`, `do_not_disturb`, `no_answer`, `voicemail`, `failed` or `other`. It is `null` when the conversation has no outcome yet. New values may be added, so treat a value you don't know as `other`.

## Errors

| Status | When |
| - | - |
| `400` | A query value is not valid, `channel` does not match `type`, `direction` is set for a chat or web conversation, or an account key leaves out `workspaceId` |
| `402` | The account has no plan, or its subscription is not active |
| `404` | The workspace does not exist, or this key can't read it |

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.nedzo.ai/v1/conversations?workspaceId=789e4567-e89b-12d3-a456-426614174000&type=voice&limit=20" \
      -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "items": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "workspaceId": "789e4567-e89b-12d3-a456-426614174000",
        "type": "voice",
        "channel": "call",
        "direction": "outbound",
        "status": "closed",
        "agentId": "456e4567-e89b-12d3-a456-426614174000",
        "contactId": "321e4567-e89b-12d3-a456-426614174000",
        "outcome": "appointment_booked",
        "summary": "The caller booked a cleaning for Tuesday at 10am.",
        "startedAt": "2026-10-01T15:02:11Z",
        "endedAt": "2026-10-01T15:05:40Z",
        "durationSeconds": 209,
        "createdAt": "2026-10-01T15:02:05Z",
        "updatedAt": "2026-10-01T15:06:02Z"
      }
    ],
    "total": 342,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
  ```
</ResponseExample>


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