Find a time
free_times_findFind when the person is free or available - an open slot for a meeting, a call or an appointment - in every connected calendar: each stretch of a window that no busy time touches and that is at least as long as the meeting. An event holds its time as its provider's own free/busy shows it: on Google unless shown as available or declined - an invitation not yet answered or answered maybe included - on iCloud or a calendar server unless shown free or declined, and on Outlook only when shown busy or away, so an Outlook tentative answer leaves its time free; a cancelled event holds none. An all-day event holding time holds its whole day in the person's own time zone. The search never starts before now, keeps to every preference preferences_get names and to the window's first 365 days and, where the call names them, to hours on each day and to weekdays on top of those preferences; limit keeps the earliest stretches. Once any day has working hours, a day without them is off. The buffers pad the meeting being booked: a stretch starts buffer_before_minutes after busy time ends and ends buffer_after_minutes before the next begins. Each stretch answers once, in time order, with its parts inside the preferred times under preferred. Times, hours and weekdays are in the zone the call names, else the person's own; the stored working hours and preferred times are in the person's own. searched names the window searched and narrowedBy what narrowed it: notice, the least notice from now, rounded up to the quarter hour; horizon, to the end of its last day; yearCap, the 365 days; readLimit, a calendar holding more events than a search reads, read as far as it could be and searched to two days before the last it read; daysOff, days without working hours; fullDays, days already holding the most meetings in a day, a meeting being an event of some length that holds time inside that day's working hours. A calendar or account named under unread was not counted, nor were the calendars past the first 100 of an account under cutShort, so their busy time may fall inside a stretch. An account named under unread as needs_reconnection carries its own row under reconnectAt, where the person, signed in as the same account, presses "Reconnect"; calls to it answer again only once they have.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End of the window, excluded, with its offset. | |
| from | Yes | Start of the window, included, with its offset, e.g. 2026-10-12T09:00:00+01:00. | |
| hours | No | Only these hours of each day, e.g. 10:00-16:00 or 09:00-12:00, 14:00-17:00. | |
| limit | No | At most this many stretches, the earliest. | |
| minutes | No | Meeting length in minutes; the stored one where omitted. | |
| timeZone | No | An IANA zone such as Europe/London the answer is given in; the stored one where omitted. | |
| weekdays | No | Only these days of the week. |