Usage & Limits
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). 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:
ratesdoes not move when a custom rate expires (itsexpires_atpasses) or its dates pass andGET /listings/{listing_id}/custom_ratesstops 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 onexpires_atandend_dateyourself.flags.detecteddoes not fire when a flag is cleared. To see cleared flags, re-readGET /listings/{listing_id}/flagson your own schedule.recent_changesdoes not report reservations or the price calendar. Reservations are covered byreservations.ingested. Neither webhooks norrecent_changesreport price calendar changes, so re-readGET /listings/{listing_id}/price_calendaron your own schedule.recent_changescosts one request per listing.GET /preferencesreads the preferences of several listings in one request, which can cost less than onerecent_changescall per listing.