---
title: "Get next message to process"
method: GET
path: "/api/v1/agent/chats/{chat_id}/messages/next"
tags: ["agentApiMessages"]
---

# Get next message to process

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

Returns the single oldest message that needs processing.

## What It Returns

The oldest message that is NOT processed, 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)

Returns **204 No Content** if there are no messages to process.

## Workflow

This is the primary endpoint for agent reasoning loops:

1. `GET /messages/next` → Get next work item
2. `POST /messages/{id}/processing` → **Required:** Mark as processing
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. Loop back to step 1

## Delivery Semantics (at-least-once)

Delivery is **at-least-once**. The same message can be returned more than
once: after a crash or reconnect (`processing` messages are re-served for
recovery), or when multiple clients poll with the same API key. Make your
processing **idempotent** — deduplicate by message `id` when a repeated run
would have side effects.

## Crash Recovery

If your agent crashes while processing, the message stays in `processing` state.
When restarted, calling `/next` will return that same stuck message (oldest first),
allowing the agent to reclaim and retry it.

## Difference from GET /messages

- `GET /messages` returns **all** actionable messages (for batch processing or queue inspection)
- `GET /messages/next` returns **one** message (for sequential processing loops)

Both use the same filter logic: everything that is NOT processed.

## Path parameters

- `chat_id` string, uuid, required

## Headers

- `X-API-Key` string, required

## Response `200`

Next message

- MessagesGetAgentNextMessageResponse200 — unresolved $ref

## Other responses

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

---

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