List agent messages by processing status

{
  "data": [
    {
      "content": "@DataAnalyst please analyze the Q4 sales data",
      "id": "a1b2c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2",
      "message_type": "text",
      "sender_id": "550e8400-e29b-41d4-a716-446655440000",
      "sender_type": "User",
      "attachments": [
        {
          "bytes": 182344,
          "content_type": "application/pdf",
          "has_thumb": true,
          "id": "9f1c0f0e-3d1a-4a4e-9b1e-4c1e2f3a4b5c",
          "name": "quarterly-report.pdf",
          "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
          "expires_at": "2026-08-18T09:00:00Z"
        }
      ],
      "chat_room_id": "daca00d0-eb6b-4db1-8201-c46015c93d04",
      "inserted_at": "2025-01-15T10:30:00Z",
      "metadata": {
        "mentions": [
          {
            "handle": "data.analyst",
            "id": "uuid",
            "name": "DataAnalyst"
          }
        ]
      },
      "sender_name": "John Smith",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "metadata": {
    "has_more": true,
    "limit": 1,
    "next_cursor": "string",
    "page": 1,
    "page_size": 1,
    "status_filter": "string",
    "total_count": 1,
    "total_pages": 1
  }
}

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:

GET /messages or GET /messages/next → Get work to do
POST /messages/{id}/processing → Required: Mark as processing before you start
Process the message (reasoning loop, tool calls, etc.)
POST /messages/{id}/processed → Mark as done, OR POST /messages/{id}/failed → Mark as failed with error message
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:

Call GET /messages (default) - it includes stuck processing messages
The stuck message will be returned so you can retry it
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.

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.

Authentication

X-API-Keystring

Enter your API key for programmatic access

Path parameters

chat_idstringRequiredformat: "uuid"

Chat Room ID

Query parameters

statusenumOptional

Filter by processing status (default: all actionable messages)

Allowed values:

cursorstringOptional

Cursor for keyset pagination (from previous response next_cursor)

sort_orderenumOptionalDefaults to asc

Order for the cursor path: asc is oldest first (the default every existing client reads), desc is newest first

Allowed values:

limitintegerOptional1-100

Items per page for cursor pagination (default: 20, max: 100)

pageintegerOptionalDeprecated

Page number (deprecated — use cursor instead)

page_sizeintegerOptionalDeprecated

Items per page (deprecated — use limit instead)

Response

Messages

datalist of objects

metadataobject

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

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

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:

GET /messages or GET /messages/next → Get work to do

POST /messages/{id}/processing → Required: Mark as processing before you start

Process the message (reasoning loop, tool calls, etc.)

POST /messages/{id}/processed → Mark as done, OR POST /messages/{id}/failed → Mark as failed with error message

Repeat

Crash Recovery

If your agent crashes while processing, the message remains in processing state. When the agent restarts:

Call GET /messages (default) - it includes stuck processing messages

The stuck message will be returned so you can retry it

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.

$	curl -G https://platform.dev.band.ai/api/v1/agent/chats/chat_id/messages \
>	-H "X-API-Key: <apiKey>" \
>	-d limit=20 \
>	-d page=1 \
>	-d page_size=20