---
title: "GET /threads"
method: GET
path: "/threads"
---

# GET /threads

`GET /threads`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/threads`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

## Query parameters

- `channel` 'EMAIL': Channel to list conversations for. EMAIL is currently the only supported value — SMS/MMS conversations are listed by GET /sms/threads, which models them as a phone-number pair rather than a reply chain.
- `agentId` string: Filter conversations to one agent. Optional for master keys (omit for every agent in the org); ignored for agent keys, which always see only their own.
- `inboxId` string: Filter conversations to one inbox — the precise way to read a single mailbox.
- `direction` 'INBOUND' | 'OUTBOUND': Only conversations containing a message in this direction. `OUTBOUND` is a Sent view. Note that the returned counts then describe the MATCHING messages, not the thread's full length.
- `labels` string[]: Filter to messages carrying ALL of these labels (e.g. `urgent` + `unread` means urgent AND still unread). Case-insensitive. System labels: `unread`, `read`, `archived`, `spam`.
- `includeSpam` boolean: Include messages classified as spam on arrival. They are excluded by default. Naming `spam` in `labels` also counts as asking for it, so a deliberate spam query is never silently emptied by this default.
- `includeArchived` boolean: Include messages carrying the `archived` label. They are excluded by default, so archiving actually removes mail from a listing rather than only tagging it. Naming `archived` in `labels` also counts as asking for it (and returns ONLY archived mail); use this flag instead to see archived mail mixed in with the rest.
- `deleted` 'exclude' | 'include' | 'only': How to treat messages moved to Trash. `exclude` (default) hides them, so deleted mail disappears from every ordinary listing. `only` returns nothing but Trash. `include` ignores the distinction. Deletion is reversible — see DELETE /messages/{id} and POST /messages/{id}/restore.
- `limit` integer: Maximum conversations to return per page (1–100, default 20)
- `offset` integer: Conversations to skip, for paging through the list

## Response `200`

OK

- object: Paginated list of email conversations
  - `items` object[], required: Conversation summaries, most recent activity first
    - `threadId` string, required: Conversation identifier — the id of the thread's first message. Pass to GET /email?threadId= to read the messages.
    - `agentId` string, required: Agent that owns this conversation
    - `subject` string, nullable, required: Subject of the most recent message in the thread, or null if it has none
    - `participants` string[], required: Distinct senders and To recipients across the thread, lowercased and de-duplicated, including the agent's own address. NOT exhaustive: Cc'd correspondents are absent (they are recorded on the message, but this list is built from the From and To fields only), and Bcc recipients are absent because they are never recorded at all — by design. Treat this as 'who is visibly on the thread', not as the full recipient set; read the messages themselves if you need every address.
    - `messageCount` integer, required: Messages in the thread matching this query. Equals the thread's full length for an unfiltered listing; under a `direction` or label filter it counts only the matching messages, since a thread is listed when ANY of its messages matches.
    - `unreadCount` integer, required: How many of those messages still carry the `unread` label — what a thread list needs to be worth scanning.
    - `lastMessageAt` string, date-time, required: When the most recent message arrived or was sent — the sort key for this list
    - `lastMessageSnippet` string, required: First 140 characters of the most recent message, quoted chain already stripped where possible, so a thread list costs a snippet rather than a mail history
    - `lastMessageDirection` 'INBOUND' | 'OUTBOUND', required: Whether the most recent message was received or sent — i.e. is the ball ours
  - `total` integer, required: Total conversations matching the query
  - `hasMore` boolean, required: Whether more conversations exist past this page

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)