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

# List Conversations

> Read a workspace's inbox — every conversation with its thread, unread count, tags and status, with filters and pagination.

<Note>
  This is the inbox behind the Tuco unibox. One call gives you the conversation
  list with each thread's messages, so you can build your own inbox UI.
</Note>

## Endpoint

* **Method**: `GET`
* **Path**: `/api/unibox/conversations`
* **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` (workspace key)

## Two things that surprise people

**A conversation is keyed by recipient, not by lead.** There is no `leadId` on a
conversation — it is identified by the phone number or email address at
`recipient`. That is also why the deep link is `?conversation=<address>`.

**The thread holds what actually went out or came in.** Messages still `queued`,
`pending` or `scheduled` are deliberately **not** in it — a conversation shows
history, not intent. Read the outbound queue from
[`/api/unibox/scheduled`](#the-pending-queue) instead. If you expect "everything
for this contact" here, you will wrongly conclude the follow-ups were lost.

## Pagination

| Param | Default | Notes |
| - | - | - |
| `limit` | `50` | **Capped at 100.** A larger value is silently reduced — read `pagination.limit` back |
| `page` | `1` | Offset paging |
| `cursor` | — | Opaque cursor from `pagination.nextCursor`. Preferred for deep paging |
| `messageLimit` | unlimited | Cap the messages carried per conversation. Use a small N for a list view, then re-fetch one thread with `?conversation=` |

```json theme={null}
"pagination": {
  "page": 1,
  "limit": 50,
  "totalCount": 128,
  "totalPages": 3,
  "nextCursor": "eyJsYXN0TWVzc2FnZUF0IjoiMjAyNi0xMC0wN1QxODoy…",
  "hasMore": true
}
```

## Filters

All are query params and all intersect.

| Param | Matches |
| - | - |
| `tag` | Conversations whose lead carries this tag |
| `status` | Conversation state, e.g. `unread` |
| `line` | Only conversations on this sending line (`lineId`) |
| `conversation` | One thread, by recipient address. URL-encode a `+` as `%2B` |
| `contactOwner` | The workspace member who owns the contact |
| `propertyKey` + `propertyOp` + `propertyValue` | A custom-property comparison. `propertyStandard=true` targets a standard field |

```bash theme={null}
curl "https://app.tuco.ai/api/unibox/conversations?limit=25&tag=vip&status=unread" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx"
```

## Response

```json theme={null}
{
  "conversations": [
    {
      "id": "…",
      "recipient": "+15558880001",
      "recipientName": "Dana Reyes",
      "recipientType": "phone",
      "lastMessageAt": "2026-10-07T18:22:05.117Z",
      "unreadCount": 1,
      "status": "unread",
      "tags": [],
      "leadTags": ["vip"],
      "messages": [
        { "status": "sent", "direction": "outbound", "body": "Hi Dana" },
        { "status": "delivered", "direction": "inbound", "body": "Tell me more" }
      ]
    }
  ],
  "pagination": { "page": 1, "limit": 25, "totalCount": 1, "totalPages": 1, "nextCursor": null, "hasMore": false }
}
```

## The pending queue

Anything not yet sent:

```bash theme={null}
curl https://app.tuco.ai/api/unibox/scheduled \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx"
```

To stop it going out, see [Cancel Pending Messages](/api-reference/endpoint/cancel-for-lead).

## Related

* `GET /api/unibox/tags` — the tags you can filter on
* `GET /api/unibox/custom-properties` — the property keys for `propertyKey`
* `GET /api/replies` — a flat, paginated feed of inbound replies
* `POST /api/unibox/mark-read`, `/archive`, `/flag`, `/send-reply` — act on a conversation

<Warning>
  `GET /api/unibox/stream` (server-sent events) is **browser-only** and rejects API
  keys. For server-side updates use [webhooks](/api-reference/endpoint/create-webhook) —
  `message.reply` fires on every inbound message.
</Warning>

## Error responses

| Status | When |
| - | - |
| `401` | Missing or invalid key |
| `403` | An agency key (`tucoagency_…`) was used — this is per-workspace |


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