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

# List Thread Messages

> Retrieve the messages of a thread, one page at a time

Returns the messages of a conversation thread, oldest first by default. Narrow it to one conversation with `session_id` (the `id` from [List Conversations](https://docs.contactship.ai/api-reference/endpoint/list-conversations.md)) or to a time window with `from` and `to`.

## Headers

**x-api-key** `string` *required*

Your API key for authentication. An organization key reads any thread of the organization. A personal key needs the `messages.read` permission and reads only the threads its user can see in the inbox.

## Path Parameters

**threadId** `string` *required*

The UUID of the thread.

## Query Parameters

**session\_id** `string`

UUID of a conversation of this thread: only its messages are returned. Messages from before conversations were tracked have no `session_id` and are left out by this filter.

**from** `string`

Only messages created at or after this instant (ISO 8601, e.g. `2026-11-10T00:00:00-05:00`).

**to** `string`

Only messages created before this instant (ISO 8601). It cannot be before `from`.

**order** `string` (default: asc)

Sort direction by creation date: `asc` (oldest first) or `desc`.

**limit** `number` (default: 50)

Messages per page, from 1 to 100.

**offset** `number` (default: 0)

Number of messages to skip for pagination, up to 10000.

## Response

**data** `array`

Messages of the page.

**Message object**

**id** `string`

Unique identifier of the message (UUID).

**thread\_id** `string`

UUID of the thread.

**session\_id** `string`

UUID of the conversation the message belongs to, or `null`.

**created\_at** `string`

When the message was created (ISO 8601).

**role** `string`

Who wrote it: `user` (the contact), `agent` (the AI agent), `human` (a person on your team) or `system`.

**sender\_id** `string`

UUID of the team member who sent it from the app. `null` for the contact, the AI agent, and messages sent with an API key or by an automation.

**type** `string`

Message type, e.g. `text`, `image`, `audio`, `video`, `document`, `template`, `location`, `reaction`, `sticker`. `null` on internal notes.

**content** `string`

Text of the message, or the caption of a media message.

**media** `object`

The attachment of a media message, or `null`. `media.internal_data` carries `file_name`, `mime_type` and, when available, `file_size` and `url`.

**components** `array`

The components of a template message (header, body, buttons), or `null`.

**status** `string`

`received` for messages from the contact; `sent`, `delivered`, `read` or `failed` for messages sent to them. `null` on internal notes.

**is\_note** `boolean`

`true` for internal notes of your team. The contact never sees them.

**is\_reply** `boolean`

`true` when the message quotes an earlier one.

**is\_follow\_up** `boolean`

`true` when it is an automatic follow-up of the AI agent.

**from\_campaign** `boolean`

`true` when it was sent by a messaging campaign.

**pagination** `object`

**Pagination object**

**page** `number`

Page number, from 1.

**total\_rows** `number`

Messages that match the filters.

**total\_pages** `number`

Pages at the requested `limit`.

## Error Codes

* `400 Bad Request` — `threadId` or `session_id` is not a UUID, a date is not ISO 8601, or `to` is before `from`
* `401 Unauthorized` — Invalid or missing API key
* `403 Forbidden` — The thread belongs to another organization, or the personal key's user cannot see it
* `404 Not Found` — Thread not found
* `429 Too Many Requests` — Rate limit exceeded, see [Rate limits](https://docs.contactship.ai/api-reference/rate-limits.md)
* `500 Internal Server Error` — Server-side error

## Code Examples

```bash cURL — One conversation theme={null}
curl -X GET "https://api.contactship.ai/v1/thread/thr-b2c3d4e5-f6a7-8901-bcde-f12345678901/messages?session_id=5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f&limit=100" \
  -H "x-api-key: your-api-key"
```

```bash cURL — Time window theme={null}
curl -X GET "https://api.contactship.ai/v1/thread/thr-b2c3d4e5-f6a7-8901-bcde-f12345678901/messages?from=2026-11-10T00:00:00Z&to=2026-11-12T00:00:00Z" \
  -H "x-api-key: your-api-key"
```

```javascript JavaScript theme={null}
const threadId = 'thr-b2c3d4e5-f6a7-8901-bcde-f12345678901';
const messages = [];
for (let offset = 0; ; offset += 100) {
  const response = await fetch(
    `https://api.contactship.ai/v1/thread/${threadId}/messages?limit=100&offset=${offset}`,
    { headers: { 'x-api-key': 'your-api-key' } }
  );
  const { data, pagination } = await response.json();
  messages.push(...data);
  if (offset + 100 >= pagination.total_rows) break;
}
messages
  .filter((m) => !m.is_note)
  .forEach((m) => console.log(`[${m.created_at}] ${m.role}: ${m.content}`));
```

```python Python theme={null}
import requests

thread_id = 'thr-b2c3d4e5-f6a7-8901-bcde-f12345678901'
response = requests.get(
    f'https://api.contactship.ai/v1/thread/{thread_id}/messages',
    headers={'x-api-key': 'your-api-key'},
    params={'session_id': '5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f', 'limit': 100},
)
for message in response.json()['data']:
    print(message['created_at'], message['role'], message['content'])
```

```json Example Response theme={null}
{
  "statusCode": 200,
  "data": [
    {
      "id": "msg-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "thread_id": "thr-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "session_id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "created_at": "2026-11-14T15:03:26Z",
      "role": "user",
      "sender_id": null,
      "type": "text",
      "content": "Hi, can I move my delivery to Friday?",
      "media": null,
      "components": null,
      "status": "received",
      "is_note": false,
      "is_reply": false,
      "is_follow_up": false,
      "from_campaign": false
    },
    {
      "id": "msg-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "thread_id": "thr-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "session_id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "created_at": "2026-11-14T15:21:10Z",
      "role": "human",
      "sender_id": "u1v2w3x4-y5z6-7890-abcd-ef1234567890",
      "type": "text",
      "content": "Done, your delivery is now on Friday the 20th.",
      "media": null,
      "components": null,
      "status": "read",
      "is_note": false,
      "is_reply": false,
      "is_follow_up": false,
      "from_campaign": false
    }
  ],
  "pagination": {
    "page": 1,
    "total_rows": 2,
    "total_pages": 1
  }
}
```


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