# 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-10-20

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

## Response

```json
{
  "message": {
    "requestId": "f2a283fd-…",
    "status": "replied",
    "done": true,
    "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.

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?

Every 5 to 10 seconds. Polling spends the agent-message limit of 30 calls a minute per token. To wait without polling, send the message with `waitSeconds`. A background task can run for up to 25 minutes; poll it every minute or so.

### 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?

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