The availability endpoint supports querying multiple venues in a single request, enabling search and discovery experiences backed by locally cached availability data.

Markets

Markets are geographic regions (e.g. "New York", "London") that group venues. Use GET /v2/markets to retrieve available markets, then pass market_id to scope availability queries.

Requires scope: markets:read

GET /v2/markets
Authorization: Bearer <ACCESS_TOKEN>

Response:

{
  "data": [
    { "id": "abc-...", "name": "New York" },
    { "id": "def-...", "name": "Los Angeles" }
  ]
}

You can also filter GET /v2/venues by market:

GET /v2/venues?market_id={uuid}

Query Modes

Single venue (existing behavior):

GET /v2/availability?venue_id={uuid}&date=2026-04-01&party_size=4

Market-scoped (all venues in a market):

GET /v2/availability?market_id={uuid}&date=2026-04-01&party_size=4

Specific venues (max 100):

GET /v2/availability?venue_ids[]={uuid1}&venue_ids[]={uuid2}&date=2026-04-01&party_size=4

Combined (intersection of market and venue list):

GET /v2/availability?market_id={uuid}&venue_ids[]={uuid1}&date=2026-04-01&party_size=4

When venue_id is omitted, at least one of market_id or venue_ids[] must be provided. The response only includes venues with active agreements for the entity's program.

Date Range Queries

The through parameter enables multi-day lookahead (max 30 days):

GET /v2/availability?market_id={uuid}&date=2026-04-01&through=2026-04-14&party_size=4

When through is omitted, availability is returned for the single date only. The modifying_reservation_id parameter cannot be used with date range queries.

Response Format

All availability queries return a venue-grouped response:

{
  "data": [
    {
      "venue_id": "aaa-...",
      "options": [
        { "option_id": "opt_xxx", "date": "2026-04-01", "time": "19:00", "party_size": 4, "seating_area": null }
      ]
    },
    {
      "venue_id": "bbb-...",
      "options": []
    }
  ]
}

Venues with no availability (e.g. blacked out, outside booking window, fully booked) appear with empty options: [].

Caching Best Practices

• Refresh every 30 minutes — option IDs have a 1-hour TTL, so 30-minute refreshes keep them well within validity
• Use option_id from cached data directly in POST /v2/holds or POST /v2/reservations
• Query by market (~15-30 venues) rather than large venue_ids[] arrays for optimal performance
• Store the full response locally to power search/filter UIs without additional API calls

Rate Limits

Multi-venue queries have a dedicated throttle of 10 requests per minute per client (vs 1,000/min for standard endpoints). This accommodates 30-minute refresh cycles with headroom for retries.

If you exceed the multi-venue limit, you'll receive 429 Too Many Requests with a Retry-After header. Single-venue availability queries (venue_id present) are not affected by this limit and use the standard 1,000/min throttle.