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?
Section titled “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.
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": "[email protected]" }, { "email": "[email protected]" }, { "email": "[email protected]" } ], "availability_rules": { "availability_method": "collective" } }'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": [ ], "availability_rules": {"availability_method": "collective"}, })
for slot in response.data.time_slots: print(slot.start_time, slot.end_time)How do I get availability slots from the Google Calendar API in Python?
Section titled “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 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.
How do I show open time slots with a calendar availability API?
Section titled “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, which covers buffers and per-participant working hours.
Find group availability from the terminal
Section titled “Find group availability from the terminal”Scheduling across a group is where free/busy intersection earns its keep. The Nylas CLI 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.
nylas calendar find-time \ --duration 1h \ --days 7find-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 and calendar availability check command reference.
Tune the slots for a team
Section titled “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 guide covers round-robin tuning in depth.
When should you use raw Free/Busy instead?
Section titled “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
Section titled “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
Section titled “What’s next”- Find open meeting times for the slot request with buffers and working hours
- Check availability to configure availability methods and per-participant open hours
- Check free/busy status for raw busy blocks and custom overlap logic
- Group availability and booking best practices for round-robin and max-fairness tuning