API ReferenceCalendars

List free/busy

List the busy times on the external calendars that providers check for conflicts. Busy times never include event titles, attendees, or other event details, and exclude appointments that SavvyCal synced to a calendar.

calendars lists every calendar checked. Busy times from a calendar with a status of failed are missing.

A request covers at most 42 days and 25 providers. Results may be up to 60 seconds old. This endpoint allows 30 requests per minute per bearer token or user.

GET
/v1/free_busy

Authorization

authorization
AuthorizationBearer <token>

In: header

Query Parameters

provider_ids*string

Comma-separated provider IDs, up to 25.

from*string

First date of the range (ISO date format), in time_zone.

Formatdate
until*string

Last date of the range (ISO date format), in time_zone. The range includes this date and spans at most 42 days.

Formatdate
time_zone?string

IANA time zone used to interpret from and until and to format timed busy times.

Default"Etc/UTC"

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/free_busy?provider_ids=prv_123456789012%2Cprv_234567890123&from=%222025-04-01%22&until=%222025-04-30%22&time_zone=%22America%2FNew_York%22"
{  "data": {    "busy_times": [      {        "calendar_id": "excal_123456789012",        "end_at": "2025-04-01T10:00:00-04:00",        "is_all_day": false,        "provider_id": "prv_123456789012",        "start_at": "2025-04-01T09:00:00-04:00"      },      {        "calendar_id": "excal_123456789012",        "end_at": "2025-04-04",        "is_all_day": true,        "provider_id": "prv_123456789012",        "start_at": "2025-04-03"      }    ],    "calendars": [      {        "error": null,        "id": "excal_123456789012",        "name": "Work",        "provider_id": "prv_123456789012",        "status": "ok"      },      {        "error": "reauthorization_required",        "id": "excal_234567890123",        "name": "Personal",        "provider_id": "prv_234567890123",        "status": "failed"      }    ],    "time_zone": "America/New_York"  }}