List available time slots for a date
GET/v2/experiences/{experienceId}/availability/slots
Requires your API key in the X-API-Key header.
Returns slot-level availability for a single date, broken down by option. Every active option of the experience appears in the response (or just one when optionId is passed): options with bookable slots carry them sorted by start time with unavailabilityReason: null; options without carry an empty slots array and a machine-readable reason. Visibility and participant semantics are identical to the dates endpoint.
For experiences synced from an external provider (Bokun/Regiondo/Kompas), the provider's availability for the requested date is refreshed best-effort before computing the response.
Option unavailability reasons
PARTICIPANT_TYPE_MISMATCH — the option disables one of the requested participant types. MAX_PARTICIPANTS_EXCEEDED — no visible variant can hold the requested party. NO_SLOTS — no availability slots exist for the option on this date. SOLD_OUT — slots exist but none has sufficient remaining capacity.
Variants
Each option also lists its visible variants with a per-variant isAvailable flag; the only per-variant reason is MAX_PARTICIPANTS_EXCEEDED (the variant's maxParticipants is below the requested party size).
Discounts
Each bookable slot carries the discount a booking made now would get: the option's early-bird discount when booking far enough in advance (type: EARLY_BIRD) or the best matching scheduled availability discount (type: AVAILABILITY), or null.
curl "https://api.turneo.co/v2/experiences/8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f/availability/slots?date=2026-07-14" \
-H "X-API-Key: <your-api-key>"Path parameters
experienceIdstring (uuid)requiredUUID of the parent experience.
- Example:
8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f
Query parameters
datestring (date)requiredThe date to check, local to the experience,
YYYY-MM-DD.- Example:
2026-07-14
participantsstringRequested party as comma-separated
participantTypeId:countpairs (counts must be positive; all type ids must be active types of this experience). When omitted, availability is evaluated for a single participant with no type filtering; the real party is validated at booking time.- Example:
a7c53f01-6f9c-4d1c-9c30-1c19a1a5bd44:2,b8d64e12-7a0d-4e2d-8d41-2d2ab2b6ce55:1
optionIdstring (uuid)Narrow the availability check to a single option. Must be a valid UUID (400 otherwise). The snake_case alias
option_idis accepted during migration.- Example:
3d3f9c2a-1b2c-4d5e-8f90-a1b2c3d4e5f6
restrictedbooleanVariant visibility filter.
false— public variants only;true— restricted (member-only) variants, falling back to public ones when the option has no active restricted variants; omitted — no filtering. Any value other thantrueis treated asfalse.- Example:
false
Responses
200object
Per-option slot availability for the date.
experienceIdstring (uuid)The experience id from the URL.
- Example:
8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f
datestring (date)Echo of the requested date.
- Example:
2026-07-14
optionsmap of objectMap of option id → availability. Every active (non-custom) option of the experience is present (or only the requested one when
optionIdis passed). Keys are option UUIDs.Child fields
slotsobject[]Bookable slots sorted by start time. Empty when the option is unavailable — see
unavailabilityReason.Child fields
slotIdstring (uuid)The availability slot id — pass it when creating a booking on this slot.
- Example:
6a5b4c3d-2e1f-4a9b-8c7d-6e5f4a3b2c1d
startTimestringnullableLocal start time,
HH:MM:SS.nullfor DATE_ONLY options (the slot spans the whole day).- Example:
10:00:00
discountobjectnullableDiscount a booking made right now would receive on the slot, or null.
Child fields
percentagenumberDiscount percentage.
- Example:
15
typestringEARLY_BIRD — the option's early-bird rule matched (booked far enough in advance); AVAILABILITY — the best matching scheduled option discount.
- Allowed values:
EARLY_BIRDAVAILABILITY- Example:
EARLY_BIRD
variantsobject[]Visible variants with per-variant availability. Empty when the option was skipped before variant evaluation (PARTICIPANT_TYPE_MISMATCH).
Child fields
variantIdstring (uuid)Variant id.
- Example:
4c9c2ab7-9a1d-4b8a-b6a0-5f2f8d3f7e21
namemap of stringnullableMultilingual variant name.
maxParticipantsintegernullableVariant capacity per booking; null means unlimited.
- Example:
2
isAvailablebooleanWhether this variant can hold the requested party.
- Example:
false
unavailabilityReasonstringnullableWhy the variant is unavailable — currently only MAX_PARTICIPANTS_EXCEEDED (the party exceeds
maxParticipants).nullwhen available.- Allowed values:
MAX_PARTICIPANTS_EXCEEDEDnull- Example:
MAX_PARTICIPANTS_EXCEEDED
unavailabilityReasonstringnullablenullwhen the option has bookable slots. Otherwise: PARTICIPANT_TYPE_MISMATCH — the option disables a requested participant type; MAX_PARTICIPANTS_EXCEEDED — no variant fits the party; NO_SLOTS — no slots exist on this date; SOLD_OUT — slots exist but none has capacity.- Allowed values:
PARTICIPANT_TYPE_MISMATCHMAX_PARTICIPANTS_EXCEEDEDNO_SLOTSSOLD_OUTnull
{
"experienceId": "8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f",
"date": "2026-07-14",
"options": {
"3d3f9c2a-1b2c-4d5e-8f90-a1b2c3d4e5f6": {
"slots": [
{
"slotId": "6a5b4c3d-2e1f-4a9b-8c7d-6e5f4a3b2c1d",
"startTime": "10:00:00",
"discount": {
"percentage": 15,
"type": "EARLY_BIRD"
}
},
{
"slotId": "7b6c5d4e-3f2a-4b8c-9d0e-1f2a3b4c5d6e",
"startTime": "14:00:00",
"discount": null
}
],
"variants": [
{
"variantId": "4c9c2ab7-9a1d-4b8a-b6a0-5f2f8d3f7e21",
"name": {
"en": "Standard"
},
"maxParticipants": 4,
"isAvailable": true,
"unavailabilityReason": null
}
],
"unavailabilityReason": null
},
"9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b": {
"slots": [],
"variants": [],
"unavailabilityReason": "SOLD_OUT"
}
}
}Errors
- 400
Validation failed. Inspect
errors[].fieldanderrors[].code.- 401
Missing or invalid
X-API-Keyheader.- 403
The API key is valid but not allowed to perform this action on this resource.
- 404
The resource does not exist or belongs to another partner (existence is not leaked across partners).
Error body
typestringError class.
- Allowed values:
validation_errorclient_errorserver_error- Example:
validation_error
errorsobject[]Child fields
codestringMachine-readable error code.
- Example:
required
fieldstringnullableOffending field, or null/'general' for non-field errors.
- Example:
startTime
messagestringHuman-readable message.
- Example:
This field is required.
{
"type": "validation_error",
"errors": [
{
"code": "required",
"field": "startTime",
"message": "This field is required."
}
]
}