# Group availability across calendars

Source: https://developer.nylas.com/docs/cookbook/calendar/group-availability/

You're building a scheduling feature, and the hard part isn't rendering a slot picker. It's finding the handful of times that work for five people whose calendars live on Google, Outlook, and iCloud. Pull each calendar, convert every busy block to a common time zone, intersect them, then re-run the whole thing when one event moves. Each provider returns a slightly different shape, so the overlap math breaks in a new way per integration.

This recipe shows how to compute shared free time for a group in one request, when to drop down to raw Free/Busy instead, and the participant and provider limits that decide what comes back.

## How do I build a group calendar availability feature?

Send a `POST /v3/calendars/availability` request with a `participants` array, a `start_time`/`end_time` window, and a `duration_minutes` meeting length. The API reads every participant's calendar, intersects their busy times, and returns only the slots when all of them are free. One call covers 4 providers (Google, Microsoft, iCloud, and Exchange), so a mixed team comes back in a single unified list.

The request below finds 30-minute slots for a three-person group inside a workday window. The `interval_minutes` field sets how often a candidate slot can start, and `availability_method: collective` means every participant must be free for a slot to qualify. Each `email` must map to a valid Nylas grant your project can read.

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/calendars/availability' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time": 1700125200,
    "end_time": 1700154000,
    "duration_minutes": 30,
    "interval_minutes": 30,
    "participants": [
      { "email": "amir@example.com" },
      { "email": "priya@example.com" },
      { "email": "dana@example.com" }
    ],
    "availability_rules": { "availability_method": "collective" }
  }'
```

```python [groupAvail-Python SDK]
from nylas import Client

nylas = Client(api_key="<NYLAS_API_KEY>")

response = nylas.calendars.get_availability(
    request_body={
        "start_time": 1700125200,
        "end_time": 1700154000,
        "duration_minutes": 30,
        "interval_minutes": 30,
        "participants": [
            {"email": "amir@example.com"},
            {"email": "priya@example.com"},
            {"email": "dana@example.com"},
        ],
        "availability_rules": {"availability_method": "collective"},
    }
)

for slot in response.data.time_slots:
    print(slot.start_time, slot.end_time)
```


> **Info:** 
> **New to Nylas?** Start with the [quickstart guide](/docs/v3/getting-started/) to set up your app and connect a test account before continuing here.


## How do I get availability slots from the Google Calendar API in Python?

The native path is the Google Calendar API `freebusy.query` method, which returns busy intervals per calendar that you intersect yourself. With the Nylas Python SDK you skip that step: call `nylas.calendars.get_availability()` with a `participants` list, and the response already holds the open slots. The same code reaches Outlook and iCloud attendees without a second integration.

Google's `freebusy.query` only returns busy blocks; it never computes the open time across people, and it never crosses providers. The Python sample above passes three participants and reads `response.data.time_slots` directly, where each slot carries a `start_time` and `end_time` in Unix seconds. The official [Google Calendar API freebusy reference](https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query) documents the native shape if you ever need to compare. For a single mailbox you'd use the lighter Free/Busy call instead, covered in [check free/busy status](/docs/cookbook/calendar/check-free-busy/).

## How do I show open time slots with a calendar availability API?

A calendar availability API returns ready-to-book open slots instead of raw busy data, so your UI renders the result without overlap math. The Nylas availability endpoint takes a `duration_minutes` value and a participant list, then returns every window where all participants are free. The response is a `time_slots` array you map straight to clickable buttons.

The two approaches differ in who computes the overlap. Free/Busy returns each person's busy intervals and leaves the intersection to your code. Availability does the intersection server-side across the whole group. The table below compares them, plus the native Google approach, for a multi-person scheduling feature.

| Task | Google Calendar API directly | Nylas Free/Busy | **Nylas availability** |
| --- | --- | --- | --- |
| Endpoint | `freebusy.query` | `POST /calendars/free-busy` | **`POST /calendars/availability`** |
| Returns | Busy blocks per calendar | Busy blocks per email | **Open slots across the group** |
| Cross-provider | Google only | Google, Microsoft, Exchange | **Google, Microsoft, iCloud, Exchange** |
| Slot intersection | You compute it | You compute it | **API computes it** |
| Duration input | No | No | **Yes, `duration_minutes`** |

For a request-by-request walkthrough of the open-slot call, see [find open meeting times](/docs/cookbook/calendar/find-meeting-times/), which covers buffers and per-participant working hours.

## Find group availability from the terminal

Scheduling across a group is where free/busy intersection earns its keep. The [Nylas CLI](https://cli.nylas.com/docs/commands) does it in one call: pass every attendee to `nylas calendar find-time` and it returns ranked slots that fit the whole group, scored across working hours, time quality, and timezones.

```bash
nylas calendar find-time \
  --participants alice@example.com,bob@example.com,carol@example.com \
  --duration 1h \
  --days 7
```

`find-time` weighs each candidate on a 100-point model over the next 7 days and respects per-participant zones via `--timezones`. For raw busy blocks instead of ranked picks, use `nylas calendar availability check`. See the [`calendar find-time`](https://cli.nylas.com/docs/commands/calendar-find-time) and [`calendar availability check`](https://cli.nylas.com/docs/commands/calendar-availability-check) command reference.

## Tune the slots for a team

The `availability_rules` object and per-participant settings shape what a group call returns. Set `interval_minutes` to control how often a slot can start, add a `buffer` of, for example, 15 minutes before and after so back-to-back meetings don't get suggested, and use `round_to` to snap start times to a clean boundary like the quarter hour. These keep a team's results from becoming a wall of overlapping options.

The `availability_method` field decides how the group is treated. The default is `max-availability`, but `collective` is the one you want for a single meeting where everyone must attend: it returns only slots free for all participants. The two round-robin methods, `max-fairness` and `max-availability`, distribute meetings across hosts instead of requiring all of them. Per-participant `open_hours` further restrict each person to their working hours and time zone, which matters for a team spread across regions. The [group availability and booking best practices](/docs/v3/calendar/group-booking/) guide covers round-robin tuning in depth.

## When should you use raw Free/Busy instead?

Reach for `POST /v3/grants/{grant_id}/calendars/free-busy` when you need raw busy intervals rather than computed slots, or when you're building custom overlap logic the availability rules can't express. The body needs only `start_time`, `end_time`, and an `emails` array, and the call skips slot generation entirely, which makes it the lighter request for rendering one team member's busy ranges in a UI.

Free/Busy trades convenience for control. You get each address's busy blocks and compute the group overlap yourself, which is the right call when your scheduling rules are unusual, like weighting certain people or honoring an external priority list. It also has different scale limits: one Free/Busy request accepts up to 50 email addresses for Google and 20 for Microsoft, and every address in a single call must share one provider. iCloud doesn't expose provider-side Free/Busy at all, so for an iCloud participant the availability endpoint is your only path.

## Things to know about group availability

Group availability depends on every participant's calendar being reachable, so a few limits decide what you actually get back. The most common surprise: a participant whose grant has expired skews the result toward "busy" or drops them from the calculation, which can silently hide otherwise-open slots. Plan for partial reads when you scan a large team.

The availability endpoint covers 4 providers (Google, Microsoft, iCloud, and Exchange) and excludes standard IMAP accounts, which have no calendar to read. Every timestamp in the request and response is Unix seconds in Coordinated Universal Time (UTC), so convert to each user's local zone in your own code before display. Each participant `email` must map to a valid grant in your project; an address with no grant fails validation rather than returning empty. Keep the window tight, since a multi-day scan across a dozen busy calendars returns far more candidate slots than a single workday, and your slot picker has to render all of them.

If you'd rather not build the booking interface, the Nylas Scheduler wraps this same availability engine in a hosted page and embeddable UI components. Use the raw API when you need a custom front end, and Scheduler when you want the UI handled for you.

## What's next

- [Find open meeting times](/docs/cookbook/calendar/find-meeting-times/) for the slot request with buffers and working hours
- [Check availability](/docs/cookbook/calendar/check-availability/) to configure availability methods and per-participant open hours
- [Check free/busy status](/docs/cookbook/calendar/check-free-busy/) for raw busy blocks and custom overlap logic
- [Group availability and booking best practices](/docs/v3/calendar/group-booking/) for round-robin and max-fairness tuning