---
title: "Poll a message"
method: GET
path: "/api/v1/agent/messages/{requestId}"
tags: ["API Reference"]
---

# Poll a message

`GET /api/v1/agent/messages/{requestId}`

## Request

- Base URL: `https://revnu.com`
- URL: `https://revnu.com/api/v1/agent/messages/{requestId}`
- Auth: HTTP bearer

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

Requires the `agent:message` scope.

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

## Path parameters

- `requestId` string, required

## Response `200`

``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

- object
  - `message` object, required
    - `interrupted` boolean
    - `failure` string
    - `requestId` string, required
    - `status` 'failed' | 'queued' | 'replied' | 'running', required
    - `done` boolean, required
    - `text` string, required
    - `sentAt` number, required
    - `replies` object[], required
      - `text` string, required
      - `at` number, required
    - `backgroundTasks` BackgroundTask[], required
      - `id` string, required
      - `label` string, nullable, required
      - `state` 'done' | 'failed' | 'running' | 'stopped', required
      - `startedAt` number, required
      - `endedAt` number

## Other responses

- `400`: The request is malformed; the error names the problem.
- `401`: Missing, malformed, unknown or revoked token.
- `402`: `setup_pending`: the account hasn't started its trial. Finish setup with `GET /setup`.
- `403`: The token lacks the scope in `requiredScope`.
- `404`: Unknown id, or another account's id.
- `429`: Rate limited.
- `503`: Temporarily unavailable; retry the same call.

---

[API](https://skmtc.dev/revnu/apis/revnu-api.md) · [All operations](https://skmtc.dev/revnu/apis/revnu-api/llms.txt) · [OpenAPI document](https://skmtc.dev/revnu/apis/revnu-api/revisions/52e523c2db61?raw)