---
title: "Get availability"
method: POST
path: "/v3/calendars/availability"
tags: ["Calendar"]
---

# Get availability

`POST /v3/calendars/availability`

Returns availability information for the specified user or group of users. All participants' email
addresses must be associated with valid Nylas grants, and should be unique within their application.

## Request body

- object
  - `availability_rules` AvailabilityRules
    - `availability_method` 'collective' | 'max-fairness' | 'max-availability'
    - `buffer` AvailabilityBuffer
      - `before` integer — The amount of buffer time to add before meetings, in increments of five minutes. For example, if an account has a meeting scheduled from 10:00–11:00a.m., and you set a `before` buffer of 30 minutes, Nylas treats 9:30–11:00a.m. as busy. This value must be between 0 and 120, and must be divisible by 5.
      - `after` integer — The amount of buffer time to add after meetings, in increments of five minutes. For example, if an account has a meeting scheduled from 10:00–11:00a.m., and you set an `after` buffer of 15 minutes, Nylas treats 10:00–11:15a.m. as busy. This value must be between 0 and 120, and must be divisible by 5.
    - `default_open_hours` AvailabilityOpenHours[] — A default set of open hours to apply to all participants. You can overwrite these open hours for individual participants by specifying `open_hours` on the Participant object.
      - `days` integer[] — The days of the week that the open hours settings are applied to. Sunday corresponds to `0`, and Saturday corresponds to `6`.
      - `timezone` string — The calendar's time zone as an [IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string.
      - `start` string — The start time for the open hours settings, in 24-hour time format. Nylas omits leading zeroes. The minimum start time is `0:00`, and the maximum is `23:49`.
      - `end` string — The end time for the open hours settings, in 24-hour time format. Nylas omits leading zeroes.
      - `exdates` string[] — A list of dates that Nylas excludes from the account's open hours, in `YYYY-MM-DD` format.
    - `round_robin_group_id` string — The ID on events that Nylas considers when calculating the order of round-robin participants. This is used for both max-fairness and max-availability calculations. To calculate participant order correctly, set the metadata key `key5` to the same value on any events you want to consider for the current set of round-robin participants. You can set this key to any value that helps you identify events used to calculate availability in this group (for example, `new_subscriber_onboarding`).
    - `tentative_as_busy` boolean — (Microsoft and EWS only) When `true`, Nylas treats tentative events as busy.
  - `duration_minutes` integer, required — The duration of each time slot, in minutes. The duration must be a multiple of 5 minutes.
  - `end_time` integer, required — The end of the time slot that Nylas checks availability for, in seconds using the Unix timestamp format. The time must be a multiple of 5 minutes.
  - `interval_minutes` integer — Nylas generates a time slot every `interval_minutes` (for example, every 30 minutes) and returns only slots when all participants are free. The interval must be a multiple of 5 minutes.
  - `participants` object[], required — A list of participants to get availability information for.
    - `calendar_ids` string[] — A list of calendar IDs associated with the participant's email address. If not defined, Nylas uses the participant's primary calendar ID.
    - `email` string — The participant's email address. The email address must be associated with a valid Nylas grant, and should be unique within its application.
    - `grant_id` string — The participant's Nylas grant ID.
    - `open_hours` AvailabilityOpenHours[] — An array of the participant's open hours. Nylas searches for free time slots within these hours.
      - `days` integer[] — The days of the week that the open hours settings are applied to. Sunday corresponds to `0`, and Saturday corresponds to `6`.
      - `timezone` string — The calendar's time zone as an [IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string.
      - `start` string — The start time for the open hours settings, in 24-hour time format. Nylas omits leading zeroes. The minimum start time is `0:00`, and the maximum is `23:49`.
      - `end` string — The end time for the open hours settings, in 24-hour time format. Nylas omits leading zeroes.
      - `exdates` string[] — A list of dates that Nylas excludes from the account's open hours, in `YYYY-MM-DD` format.
    - `only_specific_time_availability` boolean — When `true`, Nylas checks availability only against this participant's `specific_time_availability` entries and ignores their regular `open_hours`.
    - `specific_time_availability` AvailabilitySpecificTimeAvailability[] — An array of date and time ranges when the participant is available. Use with `only_specific_time_availability` set to `true` to restrict availability to only these windows.
      - `date` string, required — The date in `YYYY-MM-DD` format.
      - `end` string, required — The end time in `HH:MM` format (24-hour).
      - `start` string, required — The start time in `HH:MM` format (24-hour).
      - `timezone` string, required — The participant's IANA timezone for this availability window.
  - `round_to` integer — Nylas rounds each time slot to the nearest `round_to` value. For example, if a time slot starts at 9:05a.m. and `round_to` is set to `15`, Nylas rounds it to 9:15a.m. The round to value must be a multiple of 5 minutes.
  - `start_time` integer, required — The beginning of the time slot that Nylas checks availability for, in seconds using the Unix timestamp format. The time must be a multiple of 5 minutes.

## Response `200`

Return availability

- object
  - `request_id` string — The request ID.
  - `data` object — The response to a successful request to get availability for a participant.
    - `order` string[] — (Round-robin events only) The order of participants in line to attend the proposed meeting.
    - `time_slots` AvailabilityTimeSlot[], nullable — An array of the available time slots when you can create a meeting using the requested settings. This field may be `null` if no time slots are available. Treat `null` the same as an empty array.
      - `emails` string[], nullable — A list of participant email addresses for this time slot. This field may be `null`. Treat `null` the same as an empty array.
      - `start_time` integer — The start 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.
      - `event_id` string — (Group Events Only). The event ID of the group event
      - `master_id` string — (Group Events Only). The master ID of the recurring group event
      - `calendar_id` string — (Group Events Only). The calendar ID of the group event

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Rate Limit
- `504` — Provider Failure

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)