# Usage & Limits

> Web version: https://docs.usewheelhouse.com/rm/usage

## Pagination

List endpoints that return large result sets support pagination via the `page`,
`per_page`, and `offset` query parameters. `per_page` controls how many items
are returned per page (up to 100). Use `page` (1-based) or `offset` (0-based
item skip count) to advance through the result set — do not use both in the
same request. Iterate by incrementing `page` until a response returns fewer
items than `per_page`.

## Rate limits

RM API keys are rate-limited to **60 requests per minute** by default. Exceeding
this limit returns **429 Too Many Requests**. The limit resets on a rolling
one-minute window.

**Every response tells you where you stand**, so you never have to guess or
spend a request finding out:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Requests allowed per window for the key you used. |
| `X-RateLimit-Remaining` | Requests still available in the current window. Never negative. |
| `X-RateLimit-Reset` | Unix timestamp (seconds) when the window frees up. |

The request carrying the headers is itself counted, so an idle key's first
response reports one fewer than the limit.

A **429** carries the same three headers plus **`Retry-After`**, the number of
seconds to wait. Prefer `Retry-After` over your own backoff schedule when it is
present — it is the actual reset, not an estimate.

If you receive a 429 and no `Retry-After`, wait before retrying. The recommended
strategy is **exponential backoff**: after the first failure wait 1 second, then
double the delay on each subsequent retry (2 s, 4 s, 8 s, …), up to a reasonable
maximum (e.g. 60 seconds). Adding a small random jitter (±10–20% of the wait
time) prevents multiple concurrent clients from retrying in lockstep.

If your integration regularly reaches the limit, consider batching requests
(e.g. using `GET /preferences` or `PUT /preferences` for multiple listings at
once) or contact Wheelhouse to discuss a higher limit.

`GET /usage` reports volumes, error rates, and response times over a window of
up to 7 days, broken down by day, by endpoint, and by API key. It is cached for
a few minutes, so poll it on the order of minutes, not seconds, and read
`generated_at` to see how fresh a response is. Live rate-limit headroom is on
the `X-RateLimit-*` headers of any response — they are current as of that
request and cost nothing extra.

### Keeping a local copy fresh

An integration that re-reads every endpoint for every listing on a schedule
spends most of its rate limit on data that has not changed. Find out what
changed first, and re-read only that.

**Use webhooks for recommendations, reservations and flags.** Subscribe to
`recommendations.updated`, `reservations.ingested` and `flags.detected` (see
[Webhooks](https://docs.usewheelhouse.com/rm/reference/webhooks.md)). Each delivery names the listings to
re-read. `reservations.ingested` and `flags.detected` send nothing for a listing
where nothing changed. `recommendations.updated` names every active listing in a
market after its nightly pricing run, including listings whose numbers did not
move. For a listing that `reservations.ingested` names,
`GET /listings/{listing_id}/reservations` with `date_filter_type=updated_at`
returns only the reservations that changed since your last read.

**Poll `GET /listings/{listing_id}/recent_changes` for preferences and custom
rates.** No webhook covers these. The endpoint returns two timestamps:

- `settings`: when the listing's preferences last changed.
- `rates`: when a custom rate on the listing was last added, changed, split or
  removed.

Store both, and on each poll re-read only what moved:

```
for each listing:
  changes = GET /listings/{listing_id}/recent_changes
  if changes.settings != stored.settings:
    GET /preferences/{listing_id}
  if changes.rates != stored.rates:
    GET /listings/{listing_id}/custom_rates
  stored = changes
```

For a listing where nothing changed, this costs one request instead of two.
Plan around these gaps in webhooks and `recent_changes`:

- `rates` does not move when a custom rate expires (its `expires_at` passes) or
  its dates pass and `GET /listings/{listing_id}/custom_rates` stops returning
  it. Nothing is written when that happens, and such a rate no longer affects
  any future price. If your local copy should drop it at that point, filter on
  `expires_at` and `end_date` yourself.
- `flags.detected` does not fire when a flag is cleared. To see cleared flags,
  re-read `GET /listings/{listing_id}/flags` on your own schedule.
- `recent_changes` does not report reservations or the price calendar. Reservations are
  covered by `reservations.ingested`. Neither webhooks nor `recent_changes`
  report price calendar changes, so re-read
  `GET /listings/{listing_id}/price_calendar` on your own schedule.
- `recent_changes` costs one request per listing. `GET /preferences` reads the preferences of
  several listings in one request, which can cost less than one
  `recent_changes` call per listing.
