Blog

Free/busy, working hours and the booking race.

A free/busy call tells you what is on a calendar. It does not hold the time, so the slot you show can be gone by the time someone books it.

 · 6 min read

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.

freeBusy.query
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).

getSchedule
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:

  1. Re-read free/busy for the chosen slot at booking time, not from the list you showed.
  2. 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.
  3. Create the event. If that fails, release the claim.
  4. 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.find takes up to 20 attendees and a range of up to 62 days. It returns each attendee’s blocks, suggested slots, complete, unresolved and withheldReasonwithheld_reason. An address the provider cannot answer for gets an error and does not constrain the slots; requireAll: truerequire_all=True withholds every suggestion instead.
  • Hours and steps. workingHoursworking_hours takes start, end and days (default Monday to Friday) in timeZonetime_zone. Slots start on multiples of stepMinutesstep_minutes after 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_accounts reads 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, weekly hours, bufferBeforeMinutesbuffer_before_minutes, bufferAfterMinutesbuffer_after_minutes, minimumNoticeMinutesminimum_notice_minutes and maxPerDaymax_per_day. In any mode the host is the free account with the fewest bookings of that link in the last 30 days; ties go to the earliest in accountIdsaccount_ids.
  • Booking. bookings.create reads 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 (else slot_unavailable). In all mode 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 in all mode, the host in any mode) and on the link’s day. The claim fails with slot_taken when an open booking on one of those accounts overlaps the slot, and with slot_unavailable when the day already holds maxPerDaymax_per_day bookings; in any mode 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 booking cancelled, which frees the claim.
book.tsbook.py
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 ignores availabilityView. 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/sdk is 0.1.0-alpha and workwae is 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.