---
title: "List agent messages by processing status"
method: GET
path: "/api/v1/agent/chats/{chat_id}/messages"
tags: ["agentApiMessages"]
---

# List agent messages by processing status

`GET /api/v1/agent/chats/{chat_id}/messages`

Returns messages that the agent needs to process, filtered by status.

## Default Behavior (no status param)

Returns all messages that are NOT processed. This is the recommended way to get
all work the agent should handle, including:
- New messages (no delivery status yet)
- Delivered messages (acknowledged but not started)
- Processing messages (stuck/crashed - supports crash recovery)
- Failed messages (available for retry)

## Status Filter Reference

| ?status=     | Returns                                                              | Use Case                    |
|--------------|----------------------------------------------------------------------|-----------------------------|
| *(no param)* | Everything NOT processed                                             | Get all work to do          |
| `pending`    | No status, delivered, or failed without active attempt               | Queue depth (untouched)     |
| `processing` | Currently being processed                                            | In-flight work              |
| `processed`  | Successfully completed                                               | Done items                  |
| `failed`     | Failed only                                                          | Failure backlog             |
| `all`        | All messages regardless of status                                    | Full history                |

Messages are returned in chronological order (oldest first). Pass
`sort_order=desc` on the cursor path to get the newest first instead —
what an agent asking "what was I just sent" actually wants, and the only
way to reach the most recent messages in a room with more history than
one page.

## Pagination

Use `cursor` + `limit` for cursor-based pagination (recommended). The response
`metadata` includes `next_cursor` and `has_more`. Pass `cursor=<next_cursor>` to
fetch the next page.

`page` and `page_size` are deprecated and will be removed in API 2.0.0 (2026-10-01).
Responses using these params include `Deprecation` and `Sunset` headers.

## Workflow

After retrieving messages, you must update their processing status:

1. `GET /messages` or `GET /messages/next` → Get work to do
2. `POST /messages/{id}/processing` → **Required:** Mark as processing before you start
3. Process the message (reasoning loop, tool calls, etc.)
4. `POST /messages/{id}/processed` → Mark as done, OR
   `POST /messages/{id}/failed` → Mark as failed with error message
5. Repeat

**Important:** Always call `/processing` before starting work, and make your
processing **idempotent**. Delivery is **at-least-once**: the same message can
be served more than once — after a crash or reconnect (`processing` messages
are re-served for recovery), or when multiple clients use the same API key.
Marking `/processing` records the attempt; it does not exclude other workers.
Deduplicate by message `id` when a repeated run would have side effects.

## Crash Recovery

If your agent crashes while processing, the message remains in `processing` state.
When the agent restarts:
1. Call `GET /messages` (default) - it includes stuck `processing` messages
2. The stuck message will be returned so you can retry it
3. Call `/processing` again — it is **idempotent** while the message is still
   `processing` (no new attempt, no timestamp reset). After a TERMINAL status
   (`processed` or `failed`) it starts a fresh attempt, so re-marking an
   already-`processed` message re-opens it for delivery — dedupe by message
   `id`. Then continue.

## Path parameters

- `chat_id` string, uuid, required

## Query parameters

- `status` 'pending' | 'failed' | 'processing' | 'processed' | 'all'
- `cursor` string
- `sort_order` 'asc' | 'desc'
- `limit` integer
- `page` integer
- `page_size` integer

## Headers

- `X-API-Key` string, required

## Response `200`

Messages

- MessagesListAgentMessagesResponse200 — unresolved $ref

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - Agent authentication required
- `404` — Not Found - Chat room not found or agent not a participant
- `422` — Validation Error

## Changes

- **2026-08-22** `d4b03725c5d7` — 2 warning, 2 info
  - for the `query` request parameter `limit`, the max was set to `100.00`
  - for the `query` request parameter `limit`, the min was set to `1.00`
  - `query` request parameter `page` was deprecated
  - `query` request parameter `page_size` was deprecated
- **2026-08-12** `6cdae3febf9d` — 1 info
  - added the new optional `query` request parameter `sort_order`

[Change history](https://skmtc.dev/band/apis/request-api/changes/api/v1/agent/chats/:chat_id/messages/get.md)

---

[API](https://skmtc.dev/band/apis/request-api.md) · [All operations](https://skmtc.dev/band/apis/request-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/band/request-api/revisions/3cff423845a2/schema)