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

# GET /phone/sms/threads

`GET /phone/sms/threads`

## Request

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

## Query parameters

- `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.
- `limit` integer: Maximum conversations to return per page (1–100, default 20)
- `offset` integer: Conversations to skip, for paging through the list
- `unread` boolean: When true, return only conversations with at least one unread message

## Response `200`

OK

- object: Paginated list of SMS conversations
  - `items` object[], required: Conversation summaries, newest activity first
    - `threadId` string, required: Conversation identifier — the id of its first message
    - `agentId` string, required: Agent that owns this conversation
    - `participantAddress` string, required: The counterparty's phone number (E.164) — the other end of the conversation
    - `agentAddress` string, required: The agent's own phone number used in this conversation
    - `lastMessageAt` string, date-time, required: Timestamp of the most recent message
    - `lastMessageSnippet` string, required: First 140 characters of the most recent message's body
    - `lastMessageDirection` 'INBOUND' | 'OUTBOUND', required: Direction of the most recent message
    - `messageCount` integer, required: Total messages in the conversation
    - `unreadCount` integer, required: How many of them still carry the `unread` label. Inbound texts start unread, so this is what a conversation list needs to be triageable at all.
  - `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)