Skip to main content
The Availability API allows you to retrieve available time slots for event types and users.

​
API Version

Availability endpoints require the cal-api-version header: 
cal-api-version: 2024-09-04

​
Authentication

Availability endpoints support optional authentication:
  • API Key: Pass via Authorization: Bearer <api-key> header (optional)
  • Access Token: OAuth access token (optional)
  • Client Credentials: Use x-cal-client-id header (optional)

​
Get Available Slots

Retrieve available time slots for an event type. 
curl --request GET \
  --url 'https://api.cal.com/v2/slots?eventTypeId=123&start=2024-12-05&end=2024-12-12&timeZone=America/New_York' \
  --header 'cal-api-version: 2024-09-04'

​
Query Parameters

​
Required Parameters

​
start
string
required
Start date in YYYY-MM-DD format (e.g., “2024-12-05”)
​
end
string
required
End date in YYYY-MM-DD format (e.g., “2024-12-12”)

​
Event Type Identification

Choose one of the following methods to identify the event type:

​
Method 1: By Event Type ID

​
eventTypeId
number
The ID of the event type

​
Method 2: By Event Type Slug + Username

​
eventTypeSlug
string
The slug of the event type
​
username
string
Username of the event type owner
​
organizationSlug
string
Organization slug (if user is in an organization)

​
Method 3: By Event Type Slug + Team Slug

​
eventTypeSlug
string
The slug of the team event type
​
teamSlug
string
The team’s slug
​
organizationSlug
string
Organization slug (if team is in an organization)

​
Method 4: Dynamic Event (Multiple Users)

​
usernames
string
Comma-separated list of usernames (minimum 2). Used to find when multiple people are available.
​
organizationSlug
string
Organization slug (required for dynamic events)

​
Optional Parameters

​
timeZone
string
Timezone for the slots (e.g., “America/New_York”). Defaults to UTC.
​
duration
number
Duration in minutes. Required for:
  • Event types with multiple duration options
  • Dynamic events (defaults to 30)
​
format
string
Response format:
  • "time" (default): Returns start times only
  • "range": Returns start and end times
​
bookingUidToReschedule
string
When rescheduling, provide the booking UID to exclude its time from busy calculations

​
Response Format

​
Default Format (time)

{
  "status": "success",
  "data": {
    "2024-12-05": ["09:00", "09:30", "10:00", "10:30"],
    "2024-12-06": ["09:00", "09:30", "10:00"],
    "2024-12-07": []
  }
}

​
Range Format

{
  "status": "success",
  "data": {
    "2024-12-05": [
      { "start": "09:00", "end": "09:30" },
      { "start": "09:30", "end": "10:00" },
      { "start": "10:00", "end": "10:30" }
    ],
    "2024-12-06": [
      { "start": "09:00", "end": "09:30" }
    ]
  }
}

​
Use Cases

​
Individual User Event Types

There are 4 ways to get slots for individual user event types:
  1. By Event Type ID 
    /v2/slots?eventTypeId=123&start=2024-12-05&end=2024-12-06&timeZone=America/New_York
  2. By Slug and Username 
    /v2/slots?eventTypeSlug=30-min&username=alice&start=2024-12-05&end=2024-12-06
  3. Within an Organization 
    /v2/slots?organizationSlug=acme&eventTypeSlug=30-min&username=alice&start=2024-12-05&end=2024-12-06
  4. Dynamic Event (Multiple Users) 
    /v2/slots?usernames=alice,bob&organizationSlug=acme&start=2024-12-05&end=2024-12-06

​
Team Event Types

There are 3 ways to get slots for team event types:
  1. By Event Type ID 
    /v2/slots?eventTypeId=456&start=2024-12-05&end=2024-12-06
  2. By Slug and Team Slug 
    /v2/slots?eventTypeSlug=team-meeting&teamSlug=engineering&start=2024-12-05&end=2024-12-06
  3. Within an Organization 
    /v2/slots?organizationSlug=acme&eventTypeSlug=team-meeting&teamSlug=engineering&start=2024-12-05&end=2024-12-06

​
Rescheduling

When rescheduling a booking, pass the booking UID to exclude its time from busy calculations: 
curl --request GET \
  --url 'https://api.cal.com/v2/slots?eventTypeId=123&start=2024-12-05&end=2024-12-06&bookingUidToReschedule=abc-123-def' \
  --header 'cal-api-version: 2024-09-04'

​
Reserve a Slot

Reserve a specific time slot temporarily (holds the slot for a short period). 
POST /v2/slots/reserve

​
Request Body

{
  "eventTypeId": 123,
  "slotUtcStartDate": "2024-12-05T14:00:00Z",
  "slotUtcEndDate": "2024-12-05T14:30:00Z"
}

​
Important Notes

​
Managed Event Types

Managed event types are templates that create individual child event types for each team member. You cannot fetch slots for the parent managed event type directly. Instead:
  1. Find the child event type IDs (assigned to specific users)
  2. Use those child event type IDs to fetch slots as individual user event types

​
Time Zones

  • All times in the response are in the specified timeZone parameter
  • If no timezone is provided, times are returned in UTC
  • Use IANA timezone format (e.g., “America/New_York”, “Europe/London”)

​
Performance

  • Keep the date range reasonable (1-4 weeks recommended)
  • Larger date ranges will take longer to compute
  • Consider caching results for frequently accessed event types

Build docs developers (and LLMs) love

Get started for freeTalk to us