> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/calcom/cal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Availability

> Check available time slots for bookings

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:

```bash theme={null}
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.

<CodeGroup>
  ```bash cURL - By Event Type ID theme={null}
  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'
  ```

  ```bash cURL - By Username and Slug theme={null}
  curl --request GET \
    --url 'https://api.cal.com/v2/slots?username=alice&eventTypeSlug=30-min&start=2024-12-05&end=2024-12-12' \
    --header 'cal-api-version: 2024-09-04'
  ```

  ```bash cURL - Dynamic Event (Multiple Users) theme={null}
  curl --request GET \
    --url 'https://api.cal.com/v2/slots?usernames=alice,bob&organizationSlug=acme&start=2024-12-05&end=2024-12-12' \
    --header 'cal-api-version: 2024-09-04'
  ```
</CodeGroup>

## Query Parameters

### Required Parameters

<ParamField query="start" type="string" required>
  Start date in YYYY-MM-DD format (e.g., "2024-12-05")
</ParamField>

<ParamField query="end" type="string" required>
  End date in YYYY-MM-DD format (e.g., "2024-12-12")
</ParamField>

### Event Type Identification

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

#### Method 1: By Event Type ID

<ParamField query="eventTypeId" type="number">
  The ID of the event type
</ParamField>

#### Method 2: By Event Type Slug + Username

<ParamField query="eventTypeSlug" type="string">
  The slug of the event type
</ParamField>

<ParamField query="username" type="string">
  Username of the event type owner
</ParamField>

<ParamField query="organizationSlug" type="string">
  Organization slug (if user is in an organization)
</ParamField>

#### Method 3: By Event Type Slug + Team Slug

<ParamField query="eventTypeSlug" type="string">
  The slug of the team event type
</ParamField>

<ParamField query="teamSlug" type="string">
  The team's slug
</ParamField>

<ParamField query="organizationSlug" type="string">
  Organization slug (if team is in an organization)
</ParamField>

#### Method 4: Dynamic Event (Multiple Users)

<ParamField query="usernames" type="string">
  Comma-separated list of usernames (minimum 2). Used to find when multiple people are available.
</ParamField>

<ParamField query="organizationSlug" type="string">
  Organization slug (required for dynamic events)
</ParamField>

### Optional Parameters

<ParamField query="timeZone" type="string">
  Timezone for the slots (e.g., "America/New\_York"). Defaults to UTC.
</ParamField>

<ParamField query="duration" type="number">
  Duration in minutes. Required for:

  * Event types with multiple duration options
  * Dynamic events (defaults to 30)
</ParamField>

<ParamField query="format" type="string">
  Response format:

  * `"time"` (default): Returns start times only
  * `"range"`: Returns start and end times
</ParamField>

<ParamField query="bookingUidToReschedule" type="string">
  When rescheduling, provide the booking UID to exclude its time from busy calculations
</ParamField>

## Response Format

### Default Format (time)

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```bash theme={null}
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).

```bash theme={null}
POST /v2/slots/reserve
```

### Request Body

```json theme={null}
{
  "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