Endpoint reference

Availability

Day-by-day availability for a known listing over a date window.

GET/v1/availability

Day-by-day availability for a known listing over a date window.

Creditsfrom 5 credits / call (Vrbo from 12)

Cache TTL6 hours

ReturnsAvailability[]

ShapeSingle

Live calls are asynchronous — you poll for the result

The sample response below is the synchronous shape you get from the sandbox (a stay_test_ key) and from live cache hits. A live (stay_live_) call that has to scrape returns HTTP 202 with a data.jobId instead of blocking. Poll GET /v1/jobs/{jobId} (always free) until data.status is completed, then read the payload below from data.result (not data); the reconstructed meta — credits, platformResults, warnings — sits at the top level. Jobs usually finish in tens of seconds but can run several minutes (240s+), so budget your wait. The @stayingapi/sdk auto-polls a 202 to completion and hands you this exact synchronous-looking envelope — the simplest way to consume the API. See the response envelope for all three shapes.

Get day-by-day availability for a known listing (or a batch of listings) on one platform over a date window. Each day reports whether it is available, its minimum-night requirement, and whether check-in / check-out / booking is allowed, where the platform states them; a rule the platform does not give is null, never a guess.

Parameters

Request parameters
Parameter	Type	Required	Default	Notes
`platform`	`enum`	Yes	—	vrbo \| booking \| airbnb \| google. Single platform (not a fan-out endpoint). Use the API value, not the brand name — "booking", not "booking-com"; "google", not "google-hotels".
`listingId`	`string`	One of	—	A single listing id on platform. For Airbnb, a pasted room URL (any Airbnb domain) is also accepted and reduced to the numeric id; anything else non-numeric returns 400 invalid_parameter. For Vrbo, pass the /v1/search platformListingId (e.g. 34181835), or the search result's url, which carries it as expediaPropertyId=. The number in a vrbo.com address (e.g. 697532 in https://www.vrbo.com/697532) is a different id that availability cannot look up: an address without expediaPropertyId, or a code such as 4768392ha, is rejected with 400 invalid_parameter (free).
`listingIds[]`	`string[]`	One of	—	A batch of listing ids on platform. Airbnb accepts one listing per call (more returns 400 invalid_parameter, free; send one call per listing). For Vrbo, each element follows the listingId rule, and at most 12 listings per call (more returns 400 invalid_parameter, free; split the call).
`country`	`string`	No	—	ISO-3166 alpha-2 country (e.g. gb). Booking.com: a bare slug (the platformListingId /v1/search returns) is ambiguous across countries, so pass the search result's location.country here — or a "{country}/{slug}" id / the full booking.com/hotel/{country}/{slug}.html URL. Without it a bare Booking slug returns 400 needs_country. Ignored by other platforms.
`url`	`string`	One of	—	Full listing URL (alternative to an id). For Vrbo it must carry expediaPropertyId= (every /v1/search result url does); otherwise 400 invalid_listing_url.
`startDate`	`date`	Yes	—	YYYY-MM-DD; not in the past.
`endDate`	`date`	Yes	—	After startDate; window ≤ 365 days.
`onlyAvailable`	`boolean`	No	`false`	If true, only bookable dates are returned.

Request & response

/v1/availability

Request

GET /v1/availability?platform=airbnb&listingId=42307961&startDate=2026-07-13&endDate=2026-07-20
Host: api.stayingapi.com
Authorization: Bearer stay_live_…

Response

{
  "data": [
    {
      "platform": "airbnb",
      "listingId": "42307961",
      "dates": [
        { "date": "2026-07-13", "available": true, "minNights": 7, "checkIn": true, "checkOut": false, "bookable": true },
        { "date": "2026-07-14", "available": true, "minNights": 7, "checkIn": false, "checkOut": false, "bookable": true }
      ]
    }
  ],
  "meta": {
    "requestId": "req_av…",
    "platforms": ["airbnb"],
    "cached": false, "partial": false,
    "creditsCharged": 5, "currency": "USD", "pagination": null,
    "platformResults": [
      { "platform": "airbnb", "status": "ok", "creditsCharged": 5, "cached": false, "count": 1 }
    ],
    "warnings": []
  }
}

Code samples

The same call in every language that matters — all returning the identical unified schema.

GET /v1/availability

curl -sS "https://api.stayingapi.com/v1/availability?platform=airbnb&listingId=42307961&startDate=2026-07-13&endDate=2026-07-20" \
  -H "Authorization: Bearer $STAYINGAPI_KEY"

Try it

Run this endpoint against the deterministic sandbox right now — a real 200, zero credits, no sign-up. The credit cost of the equivalent live call is from 5 credits / call (Vrbo from 12).

Try itsandbox · 0 credits · no sign-up

GET/v1/availability

platformlistingIdstartDateendDateAPI key (optional)

Runs against the deterministic Airbnb sandbox fixture — a real 200, zero credits.

Response

Run the call to see a live, deterministic sandbox response.

Copy as curl

curl -sS "https://api.stayingapi.com/v1/availability" \
  -H "Authorization: Bearer $STAYINGAPI_KEY"

Workflows using this

Ready-made automations built on /v1/availability — an importable n8n workflow + a portable AI-agent skill each.

Property availability watch → alert — Watch a listing over a date window and get alerted the moment a wanted date becomes available.
New-inventory monitor → CRM lead feed — Re-run a saved search on a schedule, diff it against the last run, and sync only the newly-listed properties into a CRM or Sheet as leads.
Competitor rate & availability benchmark → report — Benchmark your listing’s rate and availability against a defined comp-set and get a weekly position report.
Agent-native scouting via MCP — Connect StayingAPI as a Claude/Cursor MCP connector and scout stays, compare prices and check availability conversationally — no keys pasted.
Event / peak-date demand radar — Watch supply and prices around an event or peak date-window in a city and get alerted when demand tightens.

Notes & gotchas

Which per-day rules are real, by platform

minNights, checkIn and checkOut come from the platform itself, or are null when it does not give them. Airbnb and Vrbo: per-day calendar values. Booking.com: availability is checked for the requested stay as a whole; minNights and checkIn come from Booking's own per-date minimum-stay data for the dates it covers (else null), and checkOut is always null. Google Hotels: all three are always null. For Booking.com and Google Hotels, a /v1/price call for the exact stay is the reliable bookability check: a stay Booking.com will not sell (dates taken, below its minimum stay, no rate for the party) returns no_availability, free.

Window cap: 365 days

The startDate → endDate window must not exceed 365 days, or you get 400 invalid_request / window_too_long. Supplying more than one identifier (listingId / listingIds[] / url) returns mutually_exclusive_params.

Vrbo: rentals only, 12 listings per call

Vrbo availability answers vacation rentals. Some Vrbo listings are hotel-type and have no rental calendar: those return no dates and a no_calendar warning (a call in which no listing returns dates is not charged). Send at most 12 Vrbo listings per call; more returns 400 invalid_parameter at no charge, so split the call.