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",
      "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).

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. This prevents duplicate processing since agents doing reasoning loops will always follow the sequence: /next → /processing → do work → /processed.

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 to reset the attempt timestamp, 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). ## 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. This prevents duplicate processing since agents doing reasoning loops will always follow the sequence: `/next` → `/processing` → do work → `/processed`. ## 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 to reset the attempt timestamp, 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)

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

Messages are returned in chronological order (oldest first).

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

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