Skip to main content

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:

HeaderMeaning
X-RateLimit-LimitRequests allowed per window for the key you used.
X-RateLimit-RemainingRequests still available in the current window. Never negative.
X-RateLimit-ResetUnix 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:

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