# Poll a message

> One message's status and every reply the agent has sent since it landed.

Canonical: https://revnu.com/docs/agent-message-status
Last updated: 2026-11-02

```bash
curl -H "Authorization: Bearer $REVNU_API_TOKEN" https://revnu.com/api/v1/agent/messages/f2a283fd-…
```

## Query

| Param | Meaning |
|---|---|
| `waitSeconds` | Integer from 0 to 120, default 0. Hold this read until the request finishes, its status/replies/background tasks change, or the wait expires. No new job is submitted. |

## Response

```json
{
  "message": {
    "requestId": "f2a283fd-…",
    "status": "replied",
    "done": true,
    "completion": "agent_work_finished",
    "nextPollAfterMs": 0,
    "text": "What did we ship this week?",
    "sentAt": 1789851456304,
    "replies": [{ "text": "Three things shipped: …", "at": 1789851468121 }],
    "backgroundTasks": []
  }
}
```

`status` is `queued`, `running`, `replied` or `failed` (with a `failure` message; re-send with a new client id). `replied` means the agent answered and finished the turn. The agent may answer in more than one bubble, and it often posts progress while it works, so `replies` can fill while the status is still `running`. It is a list, oldest first, holding the latest five bubbles. `interrupted: true` means a later message stopped this turn before it finished. A message the agent picked up inside a turn that was already running reports that turn's replies.

A message that hasn't started after 30 minutes reads `failed` (six hours for one sent with `queue: true`). A started turn stays `running` while it has shown activity in the last 20 minutes, for up to 2 hours; past either, it reads `failed`.

Long research, such as building a list of 50 companies, runs as a background task: the agent replies that it has started, its turn ends with `status: "replied"`, and the research carries on. `backgroundTasks` lists each task the message started with its `id`, `label`, `state` (`running`, `done`, `failed` or `stopped`), `startedAt` and `endedAt`. A task is `done` once the agent has checked and saved its results and reported them, and that report joins `replies` (the latest ten bubbles). `done` on the message is `true` only when the turn has ended and no task is still running, so wait for `done`, not for `replied`. `404` for an unknown id, a colleague's dashboard turn, or another account's message.

## Frequently asked questions

### How often should I poll?

Use `waitSeconds=30` on this GET to continue waiting without repeated client requests. It returns the current message when the wait expires or a new update arrives. Follow `nextPollAfterMs` before checking again; it is 5,000 while work continues and zero when finished. If a later poll fails, a retryable `503` response preserves the last message and adds `waitEnded: "poll_failed"`. A deliberate refusal returns `409` with its original reason and recovery fields. A revoked token returns `401` without message data. Polling spends the agent-message limit of 30 calls a minute per token. `completion` is `in_progress`, `agent_work_finished` or `failed`. It describes the agent's work, including its background tasks. It does not establish that a draft was approved or an email sent. Read review or delivery records for those outcomes.

### Which scope does this need?

`agent:message`. A token without it gets `403` with `requiredScope` in the body. `GET /me` shows a token's scopes.

### Are responses cached?

Every response is `Cache-Control: no-store`, so what you read is always current.
