---
title: "Get free/busy schedule"
method: POST
path: "/v3/grants/{grant_id}/calendars/free-busy"
tags: ["Calendar"]
---

# Get free/busy schedule

`POST /v3/grants/{grant_id}/calendars/free-busy`

## Request

- Base URL: `https://api.us.nylas.com`
- URL: `https://api.us.nylas.com/v3/grants/{grant_id}/calendars/free-busy`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

(Not supported for iCloud) Returns the free/busy schedule for the specified
list of email addresses.

### Keep in mind

- The grant ID included in the request _must_ have access to view the provided email addresses'
free/busy data. This is usually configured by the provider.
- All specified email addresses must use the same provider.
- This endpoint always returns `200 OK`, even if one of the responses returns an error. Be sure
to check for any errors in the list of responses.
- Microsoft's availability calculation is limited to a maximum of 1,000 entries per time slot for
each email address included in the request.
- The free/busy response does not include all-day room resource bookings on Google or Microsoft.
- You can include up to 20 email addresses for Microsoft Graph, and up to 50 email addresses for Google in a single request.

## Request body

- FreebusyRequest
  - `start_time` integer, required: The start of a time block, in seconds using the Unix timestamp format. Nylas uses `start_time` and `end_time` to assess the specified account's free/busy schedule.
  - `end_time` integer, required: The end of a time block, in seconds using the Unix timestamp format. Nylas uses `start_time` and `end_time` to assess the specified account's free/busy schedule. For Google and EWS accounts, Nylas can query a timespan of up to 3 months from the `start_time`. For Microsoft Graph accounts, Nylas can query a timespan of up to 62 days from the `start_time`.
  - `emails` string[], required: A list of email addresses to check the free/busy schedules for.
  - `tentative_as_busy` boolean: When `true`, Nylas treats tentative events as busy.

## Response `200`

Free/Busy Response

- object
  - `request_id` string: The request ID.
  - `data` object[]: An array of free/busy schedules. Nylas returns one free/busy schedule for each email address specified in the request.
    - `email` string: The participant's email address.
    - `time_slots` object[], nullable: An array of busy time slots. This field may be `null` when a free/busy lookup returns an error for a specific email address.
      - `start_time` integer: The beginning of a time slot, in seconds using the Unix timestamp format.
      - `end_time` integer: The end of a time slot, in seconds using the Unix timestamp format.
      - `status` string: The status of the time slot.
      - `object` string: The object type (in this case, always `time_slot`).
    - `error` string: If Nylas encounters an error fetching data for a participant, this field contains a description of the error.
    - `object` 'free_busy' | 'error': The object type. If the request succeeds, the value is `free_busy`. If the request fails, the value is `error`.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `429`: Rate limited. The provider or Nylas throttled the request. If a provider throttles a request and says how long to wait, the `Retry-After` header gives that number of seconds. When the header is missing, retry with exponential backoff. See [429 rate limit errors by provider](/docs/api/errors/400-response/#429-rate-limit-errors-by-provider).
- `504`: Provider Failure

## Changes

- **2026-09-26** `763d6b969cd7`: 1 info
  - added the optional property `error/provider_error` to the response with the `429` status

[Operation history](https://skmtc.dev/nylas/apis/nylas-api/changes/v3/grants/:grant_id/calendars/free-busy/post.md)

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) - [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nylas/apis/nylas-api/revisions/7782a3e3ab70?raw)