Skip to content

Get Availabilities
Preview

Request

Get the availabilities of an experience within a time window.

Use this to render a calendar or a time picker. For an availability you already hold an id for, prefer Get Availability. The response is paginated; pass the returned next cursor on subsequent calls to continue.

Events and timeslots the host has closed to new bookings are left out, unless the host exempted the event.

This is a read: it creates nothing and has no side effects. The body is optional — omit it to get the first page of availabilities from the current time onwards.

Security
OAuth2(Required scopes: experience.read)
Path
experienceIdstringrequired

The unique identifier of the experience to compute availability for.

Bodyapplication/json
fromstring

Return availabilities starting on or after this local date-time (inclusive). ISO 8601 date-time without a timezone offset (e.g. 2026-07-14T08:00:00), interpreted in the timezone of the location its subject runs at. Defaults to the current time — pass it explicitly to look into the past.

Example:"2026-07-14T08:00:00"
tostring

Return availabilities starting before this local date-time (exclusive). ISO 8601 date-time without a timezone offset (e.g. 2026-07-15T00:00:00), interpreted in the timezone of the location its subject runs at. Omit it to leave the window open-ended.

Example:"2026-07-15T00:00:00"
filterobject(AvailabilityFilter)

Narrows which availabilities the window returns.

cursorstring

Pagination cursor for fetching the next page of results. Omit or pass an empty string to start from the beginning of the list.

limitinteger, (int32), [ 1 .. 100 ]

Maximum number of items to return per page. Defaults to 50, maximum 100.

Default:50
curl -i -X POST \
  'https://api.understory.io/v1/experiences/{experienceId}/availabilities' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2026-07-14T08:00:00",
    "to": "2026-07-15T00:00:00",
    "filter": {
      "event_ids": [
        "string"
      ],
      "location_ids": [
        "string"
      ],
      "durations": [
        "PT1H30M"
      ]
    },
    "cursor": "string",
    "limit": 50
  }'

Responses

OK

Bodyapplication/json
itemsArray of objects(Availability)required

The availabilities matching the query, ordered by start time.

nextstring

Cursor for the next page of results. An empty string or absent value indicates the end of the list.

Response
{
  "items": [
    { … }
  ],
  "next": "string"
}