A booking page asks one question: when is this person free? Google Calendar and Microsoft 365 both answer it with a free/busy call. The answers differ in shape and in what they leave out, and neither call reserves the time it reports. Turning a free/busy answer into a slot a stranger can book is mostly your own code.
This post covers Google’s freeBusy.query, Graph’s
getSchedule, hours, buffers, statuses, pooled availability, and the race between
showing a slot and booking it. It ends with what Workwae does and where it does not.
Google returns busy ranges and nothing else.
Freebusy: query
takes a time range and a list of calendar or group ids, and answers with a busy
list per calendar. Each range has an inclusive start and an exclusive end.
POST https://www.googleapis.com/calendar/v3/freeBusy
Content-Type: application/json
{
"timeMin": "2026-11-10T00:00:00Z",
"timeMax": "2026-11-12T00:00:00Z",
"items": [{ "id": "pat@example.com" }, { "id": "lee@example.com" }]
}
There is no status, no title and no event id. The page documents two caps:
calendarExpansionMax is at most 50 and groupExpansionMax is at most
100. A calendar that cannot be answered carries an errors entry with a reason such
as notFound, groupTooBig or tooManyCalendarsRequested;
the page says more reasons may be added. It states no maximum for the time range.
An event counts as busy by its
transparency:
opaque blocks time on the calendar, transparent does not. The events
resource also has out-of-office, focus-time and working-location types, and the free/busy page
does not say how those are reported. An id names a calendar. A user’s primary calendar has
an id that
usually matches the user’s primary email address,
so asking about an address asks about that calendar. Events on the user’s other
calendars are not in the answer.
Graph returns items, statuses and a view string.
calendar: getSchedule
takes SMTP addresses of users, distribution lists or rooms, a start and end with time zones,
and an optional availabilityViewInterval of 5 to 1440 minutes (default 30).
POST https://graph.microsoft.com/v1.0/me/calendar/getSchedule
Content-Type: application/json
{
"schedules": ["megan@contoso.com", "alex@contoso.com"],
"startTime": { "dateTime": "2026-11-10T00:00:00", "timeZone": "UTC" },
"endTime": { "dateTime": "2026-11-12T00:00:00", "timeZone": "UTC" },
"availabilityViewInterval": 30
}
Each address comes back as a
scheduleInformation
object. Its availabilityView has one character per interval: 0 free or
working elsewhere, 1 tentative, 2 busy, 3 out of office.
Working elsewhere is 0 and not 4 for backward compatibility. Its
scheduleItems are the underlying
events,
with a status of free, tentative, busy,
oof, workingElsewhere or unknown, and an optional subject,
location and isPrivate flag. The view is coarser than the items, so read the items
when you need exact times.
An address that fails carries an error with a message and response code. The
reference adds one hard limit: a calendar with more than 1000 entries in the range answers
5006. The items describe events on the user’s default calendar.
Who may ask about whom.
On Google, freeBusy.query accepts calendar.freebusy,
calendar.events.freebusy, calendar.readonly and
calendar. The ACL role
freeBusyReader
provides read access to free/busy information only. On Microsoft 365,
getSchedule needs Calendars.ReadBasic at least, as a delegated work
or school permission or an application permission. Personal Microsoft accounts are not
supported.
Working hours, buffers and statuses are yours to apply.
Free/busy says what is on the calendar, not when someone will take a meeting. Graph includes
the user’s
workingHours
(days, start, end, time zone) in scheduleInformation, set in their mailbox
settings. That time zone can differ from the Outlook zone. Google’s answer has no working
hours. A booking page therefore usually keeps its own hours per link.
Buffers are the same: widen each candidate slot and test it against the busy ranges.
Statuses need a policy. Google gives you only busy, so tentative and out of office look like a confirmed meeting. Graph distinguishes six statuses. Tentative and out of office should block. Working elsewhere says the person is reachable, so it reasonably should not. Free blocks nothing. Unknown means the provider could not tell, and the safe reading is busy.
Several people: everyone, or any one.
A collective slot needs every person free: take the union of their busy ranges and look for gaps. A round-robin slot needs one person free, and then you choose the host. Picking the free person with the fewest recent bookings spreads the load. Picking the first one gives that person every meeting.
Both providers fail per calendar, not per request. In a collective slot, dropping an unreadable calendar offers a time that person never agreed to. In round-robin, it only removes them from the pool.
A free slot is only free until someone books it.
Both calls return information, and neither holds the time. Between listing a slot and the invitee clicking it, another invitee can book it or an outside system can create an event. Creating the event is a separate call, so the steps are never atomic on the provider’s side. The booking path has to defend itself:
- Re-read free/busy for the chosen slot at booking time, not from the list you showed.
- Claim the slot in your own store before creating the event, with a uniqueness rule on host and start, so two simultaneous requests cannot both proceed.
- Create the event. If that fails, release the claim.
- When the slot is gone, say so and offer the list again. A conflict is a normal answer.
This narrows the race without closing it. An event added to the calendar directly, between the re-read and the event being created, can still overlap the booking.
How Workwae handles it.
Workwae makes one provider request per question for all addresses: freeBusy on
Google with one items entry per address, /me/calendar/getSchedule on
Graph. Busy blocks come back as busy, tentative, oof,
working_elsewhere or unknown. Google blocks are always
busy, and Graph free items are dropped. When it picks slots,
working_elsewhere does not block and the other four do.
- Find a time.
availability.findtakes up to 20 attendees and a range of up to 62 days. It returns each attendee’s blocks, suggested slots,complete,unresolvedandwithheldReasonwithheld_reason. An address the provider cannot answer for gets anerrorand does not constrain the slots;requireAll: truerequire_all=Truewithholds every suggestion instead. - Hours and steps.
workingHoursworking_hourstakesstart,endanddays(default Monday to Friday) intimeZonetime_zone. Slots start on multiples ofstepMinutesstep_minutesafter local midnight. - Caching. Answers are cached per account, attendee set and range for
AVAILABILITY_CACHE_SECONDS: 60 by default, 0 to 3600. - Several accounts.
availability.findForAccountsavailability.find_for_accountsreads up to 20 of the workspace’s accounts, each through its own calendar.mode: "all"mode="all"needs every account free.mode: "any"mode="any"needs one and names the free accounts per slot. - Scheduling links. A link stores accounts,
mode, duration, step,windowDayswindow_days, weeklyhours,bufferBeforeMinutesbuffer_before_minutes,bufferAfterMinutesbuffer_after_minutes,minimumNoticeMinutesminimum_notice_minutesandmaxPerDaymax_per_day. Inanymode the host is the free account with the fewest bookings of that link in the last 30 days; ties go to the earliest inaccountIdsaccount_ids. - Booking.
bookings.createreads each account’s calendar fresh, never from the cache, over the slot widened by the link’s buffers, and checks the start is still one the link offers (elseslot_unavailable). Inallmode a member whose calendar cannot be read makes the slot unavailable. It then claims the slot in one transaction, under locks on every account the booking occupies (all members inallmode, the host inanymode) and on the link’s day. The claim fails withslot_takenwhen an open booking on one of those accounts overlaps the slot, and withslot_unavailablewhen the day already holdsmaxPerDaymax_per_daybookings; inanymode the next free host is tried first. The event is created after the claim, with the invitee as an attendee and invitations sent. If that fails the row is deleted. Cancelling marks the bookingcancelled, which frees the claim.
import { createClient, isApiError } from "@workwae/sdk";
const workwae = createClient({ apiKey: process.env.WORKWAE_API_KEY });
// Round-robin across two accounts, without a link.
const { suggestions } = await workwae.availability.findForAccounts({
accountIds: [aliceAccountId, bobAccountId],
mode: "any",
start: new Date("2026-11-10T00:00:00Z"),
end: new Date("2026-11-14T00:00:00Z"),
timeZone: "America/New_York",
workingHours: { start: "09:00", end: "17:00" },
});
// From a stored link: list its slots, then book one.
const { items: slots } = await workwae.schedulingLinks.slots({ linkId, limit: 20 });
const [slot] = slots;
if (!slot) throw new Error("No open slots");
try {
const booking = await workwae.bookings.create({
linkId,
start: slot.start,
invitee: { name: "Ada Lovelace", address: "ada@example.com" },
});
console.log(booking.accountId, booking.eventId);
} catch (error) {
if (isApiError(error, "slot_taken")) {
// Booked meanwhile: list the slots again.
} else {
throw error;
}
}from datetime import datetime, timezone
from workwae import APIError, Workwae
workwae = Workwae()
# Round-robin across two accounts, without a link.
suggestions = workwae.availability.find_for_accounts(
account_ids=[alice_account_id, bob_account_id],
mode="any",
start=datetime(2026, 11, 10, tzinfo=timezone.utc),
end=datetime(2026, 11, 14, tzinfo=timezone.utc),
time_zone="America/New_York",
working_hours={"start": "09:00", "end": "17:00"},
).suggestions
# From a stored link: list its slots, then book one.
slots = workwae.scheduling_links.slots(link_id=link_id, limit=20).items
if not slots:
raise RuntimeError("No open slots")
slot = slots[0]
try:
booking = workwae.bookings.create(
link_id=link_id,
start=slot.start,
invitee={"name": "Ada Lovelace", "address": "ada@example.com"},
)
print(booking.account_id, booking.event_id)
except APIError as error:
if error.code == "slot_taken":
pass # Booked meanwhile: list the slots again.
else:
raise
Workwae sends booking.created and booking.cancelled webhooks.
Bookings are API-only: your application renders the page and calls these routes.
Limits.
- Availability reads the address’s primary calendar on Google and the default calendar on Microsoft 365. Events on an account’s other calendars do not block slots.
-
Workwae does not read a Microsoft 365 user’s
workingHours, and ignoresavailabilityView. Hours come from the query or the link. - A Google block is always
busy, so tentative time on Google looks like a meeting. - The claim covers bookings made through Workwae. An event added to the calendar directly between the re-check and the event’s creation can still overlap a booking.
- A booking can be created and cancelled. There is no reschedule route.
-
On CalDAV, only the account’s own availability is known unless the server supports RFC
6638 scheduling. An IMAP account with no CalDAV settings answers
calendar_disabled. - The SDKs are alpha:
@workwae/sdkis 0.1.0-alpha andworkwaeis 0.1.0a2, so their surface can still change.
The scheduling guide lists every link field, the slot and booking routes and their error codes. The calendar guide covers the free/busy routes, and Bookings covers the feature overall.