> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.respona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.respona.com/_mcp/server.

# Polling for Status

Placements are fulfilled asynchronously. After you [launch](/guides/getting-started/quickstart#4-launch-the-order) an order, its
placements move through the [placement state machine](/guides/core-concepts/orders-placements#placement-state-machine) over
minutes to days. You can observe that progress by **polling** (described here) or by subscribing to
[webhooks](/guides/core-concepts/webhooks) and being pushed each change. Polling is the simplest place to start;
webhooks avoid the poll loop once you host an endpoint.

## What to poll

* **Whole order** - `GET /rest/api/v1/orders/{order_id}` returns the order plus every placement with current status
  and live pricing. Use this for a full snapshot.
* **Single placement** - `GET /rest/api/v1/orders/{order_id}/placements/{placement_id}` returns just that placement.
  Use this to cheaply watch one placement without pulling the whole order.

Both are read-only, require only the `orders:read` scope, and never affect billing.

## How often to poll

Because placements advance on human/editorial timescales, poll **infrequently** - every few minutes is plenty, and
backing off further (e.g. every 15-30 minutes) once an order is well underway is friendlier to the
[rate limits](/guides/api-conventions/rate-limits). Poll individual placements rather than the whole order when you only care about a
subset.

A reasonable pattern:

1. After launch, poll the order every \~1-2 minutes while placements are still transient.
2. Once a placement is close to terminal (`APPROVED`), you can poll it individually.
3. Stop polling a placement once it is terminal.

## Interpreting terminal states

Stop polling a placement once it reaches one of these:

| Terminal status | Meaning                                                                |
| --------------- | ---------------------------------------------------------------------- |
| `LIVE`          | The link is placed and live. Done.                                     |
| `REJECTED`      | The placement could not be fulfilled. Credits are refunded per policy. |
| `REFUNDED`      | Credits for this placement were returned.                              |

An order reaches `COMPLETED` once all its placements are terminal (and `REJECTED` / `REFUNDED` at the order level for
the failure/refund cases). See [Credits & Billing](/guides/core-concepts/credits-billing) for how refunds settle.

## Webhooks

> **Note**
>
> **Webhooks are coming in a future version.** Signed, retried delivery of placement state transitions is planned so you
> won't have to poll. Until then, polling is the supported mechanism for v1.