List agent messages by processing status

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

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). ## 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:

pageintegerOptional

Page number

page_sizeintegerOptional

Items per page (default: 20, max: 100)

Response

Messages

datalist of objects

metadataobject

Errors