---
title: "Get available appointment slots across a date range"
description: "Multi-day availability in one call, so a booking UI or agent can show the next open days without one request per date. Each day carries the same slot objects the single-day endpoint returns. Days with no availability are still present with has_slots false, so the caller can render a full calendar strip."
---

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

Path: Channel Automation API › Calendar

`GET /api/calendar/availability/range`

Multi-day availability in one call, so a booking UI or agent can show the next open days without one request per date. Each day carries the same slot objects the single-day endpoint returns. Days with no availability are still present with has_slots false, so the caller can render a full calendar strip.

## Query parameters

- `workspace_id` (`get/api/calendar/availability/range.query.workspace_id`; string, required) — Workspace the calendar belongs to
  - example `"61395"`
- `admin_id` (`get/api/calendar/availability/range.query.admin_id`; string, required) — Admin/agent whose calendar is being queried
  - example `"61395"`
- `days` (`get/api/calendar/availability/range.query.days`; integer, optional) — Number of consecutive days to return, starting at start_date
  - min 1; max 14; default `7`
- `start_date` (`get/api/calendar/availability/range.query.start_date`; string, optional) — First day of the window. Defaults to today in the calendar's timezone.
  - format `date`; example `"2026-09-18"`
- `event_type_id` (`get/api/calendar/availability/range.query.event_type_id`; string, optional) — Restrict to a single event type. Defaults to the workspace's oldest enabled type.
  - format `uuid`
- `service_appointment_id` (`get/api/calendar/availability/range.query.service_appointment_id`; string, optional) — Required for workspaces backed by an external availability provider. Those workspaces return 400 without it rather than falling back to the native schedule, which would offer times the provider cannot honor.
- `format` (`get/api/calendar/availability/range.query.format`; string, optional) — `simple` returns the compact shape built for a live voice or text agent: every time is already rendered in the calendar's own timezone in 12-hour form, so the agent never converts or does date arithmetic. Fully booked times and days with nothing free are omitted. Pass the `id` of any entry straight back to the booking endpoint as `slot_id`. Omit this parameter for the detailed default shape.
  - one of `"simple"`

## Code samples

### cURL

```bash
curl --request GET \
  --url 'https://api.channelautomation.com/api/calendar/availability/range?workspace_id=61395&admin_id=61395'
```

### TypeScript

```typescript
const url = 'https://api.channelautomation.com/api/calendar/availability/range?workspace_id=61395&admin_id=61395';
const options = {method: 'GET'};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.channelautomation.com/api/calendar/availability/range?workspace_id=61395&admin_id=61395"

response = requests.get(url)

print(response.text)
```

## Responses

### 200

Range availability retrieved successfully

#### Example

```json
{
  "success": true,
  "format": "simple",
  "timezone": "America/Los_Angeles",
  "days": [
    {
      "date": "09/21/2026",
      "label": "Monday",
      "times": [
        {
          "id": "9497f193-774e-489e-9687-8cea9237c41d:2026-09-21T16:00:00.000Z",
          "start": "9:00 AM",
          "end": "10:00 AM"
        },
        {
          "id": "9497f193-774e-489e-9687-8cea9237c41d:2026-09-22T00:00:00.000Z",
          "start": "5:00 PM",
          "end": "6:00 PM"
        }
      ]
    }
  ]
}
```

- `success` (`get/api/calendar/availability/range.response.200.success`; boolean, optional)
  - example `true`
- `timezone` (`get/api/calendar/availability/range.response.200.timezone`; string, optional)
  - example `"America/Los_Angeles"`
- `start_date` (`get/api/calendar/availability/range.response.200.start_date`; string, optional)
  - format `date`; example `"2026-09-16"`
- `days` (`get/api/calendar/availability/range.response.200.days`; integer, optional)
  - example `3`
- `event_type_id` (`get/api/calendar/availability/range.response.200.event_type_id`; string, optional)
  - format `uuid`
- `source` (`get/api/calendar/availability/range.response.200.source`; string, optional)
  - one of `"native"`, `"external"`; example `"native"`
- `available_dates` (`get/api/calendar/availability/range.response.200.available_dates`; array<string>, optional) — External source only. Every date the provider reported slots for.
  - format `date`
- `dates` (`get/api/calendar/availability/range.response.200.dates`; array<object>, optional)
  - `date` (`get/api/calendar/availability/range.response.200.dates.date`; string, optional)
    - format `date`; example `"2026-09-18"`
  - `label` (`get/api/calendar/availability/range.response.200.dates.label`; string, optional) — today, tomorrow, or the date itself
    - example `"tomorrow"`
  - `has_slots` (`get/api/calendar/availability/range.response.200.dates.has_slots`; boolean, optional)
    - example `true`
  - `count` (`get/api/calendar/availability/range.response.200.dates.count`; integer, optional) — Number of slots that are not fully booked
    - example `1`
  - `slots` (`get/api/calendar/availability/range.response.200.dates.slots`; array<object>, optional)
    - `id` (`get/api/calendar/availability/range.response.200.dates.slots.id`; string, optional) — Unique identifier for the calendar slot
      - example `"event-uuid-1"`
    - `start_time` (`get/api/calendar/availability/range.response.200.dates.slots.start_time`; string, optional) — Start time of the appointment slot
      - format `date-time`; example `"2025-07-15T09:00:00Z"`
    - `end_time` (`get/api/calendar/availability/range.response.200.dates.slots.end_time`; string, optional) — End time of the appointment slot
      - format `date-time`; example `"2025-07-15T10:00:00Z"`
    - `is_booked` (`get/api/calendar/availability/range.response.200.dates.slots.is_booked`; boolean, optional) — Whether the slot is already booked
      - example `false`
    - `admin_id` (`get/api/calendar/availability/range.response.200.dates.slots.admin_id`; string, optional) — ID of the admin/agent assigned to this slot
      - example `"admin-uuid"`
    - `title` (`get/api/calendar/availability/range.response.200.dates.slots.title`; string, optional) — Title/name of the appointment slot
      - example `"Consultation Slot"`
    - `description` (`get/api/calendar/availability/range.response.200.dates.slots.description`; string, optional) — Description of what this slot is for
      - example `"Available for product consultation"`
    - `location` (`get/api/calendar/availability/range.response.200.dates.slots.location`; string, optional) — Location where the appointment will take place
      - example `"Virtual Meeting"`
    - `booking_type` (`get/api/calendar/availability/range.response.200.dates.slots.booking_type`; string, optional) — Type of booking allowed
      - example `"single"`
    - `max_bookings` (`get/api/calendar/availability/range.response.200.dates.slots.max_bookings`; integer, optional) — Maximum number of bookings allowed for this slot
      - example `1`

### 400

Invalid days or start_date, missing workspace_id/admin_id, or an external-source workspace queried without service_appointment_id

#### Example

```json
{
  "success": false,
  "error": "Invalid days. Expected an integer from 1 to 14"
}
```

- `success` (`get/api/calendar/availability/range.response.400.success`; boolean, optional)
  - example `false`
- `error` (`get/api/calendar/availability/range.response.400.error`; string, optional)
  - example `"Invalid days. Expected an integer from 1 to 14"`

### 500

Internal server error

#### Example

```json
{
  "error": "Internal server error",
  "details": "string",
  "success": false
}
```

- `error` (`get/api/calendar/availability/range.response.500.error`; string, optional)
  - example `"Internal server error"`
- `details` (`get/api/calendar/availability/range.response.500.details`; string, optional)
- `success` (`get/api/calendar/availability/range.response.500.success`; boolean, optional)
  - example `false`

### 502

External availability provider unavailable. No native fallback is served.

### 503

Existing bookings could not be read, so capacity cannot be verified


Source: https://developer.channelautomations.com/api/get-api-calendar-availability-range/index.md