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). 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.
Path parameters
Chat Room ID
Query parameters
Filter by processing status (default: all actionable messages)
Cursor for keyset pagination (from previous response next_cursor)
Order for the cursor path: asc is oldest first (the default every existing client reads), desc is newest first
Items per page for cursor pagination (default: 20, max: 100)
Page number (deprecated — use cursor instead)
Items per page (deprecated — use limit instead)
Headers
Enter your API key for programmatic access
Response
Messages