Find a time for a circle
circles_free_times_findFind when everyone in one of the person's circles - family, friends or a team - is free or available: each stretch of a window that no member's busy time touches and that is at least as long as the meeting, in the zone the call names, else the person's own - the same whichever member asks, save for a member with no calendar connected, counted by the asker's own polls. The calendars each member owns and counts as busy - never one someone else shared with them - are read through that member's own connection as the call is made, and come back under busy only as when that member is busy - the circle's owner named owner, every other member by the address invited - never what an event says. 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 its member's time zone; no one's stored working hours or other preferences apply, only the hours and weekdays the call names, in the answer's zone; limit keeps the earliest stretches, and the search keeps to the window's first 365 days. A member none of whose calendars could be read is named under unknown, and one only some of whose could under readInPart, their busy time read counted; either's busy time may fall inside a stretch. A member with no calendar connected counts as free only at the times they ticked in the person's own polls for this circle, and until they answer one is named under noCalendar - polls_create naming the circle asks them. On the person's own circle each address invited that has not joined is named under notJoined and counts the same way once it answers such a poll. Anyone counted by polls whose answers tick no time in the window is named under tickedNothing. Each stretch names under members every other member's own time for it in the zone they stored, marked unusual where any of it falls outside 09:00-18:00 or on a Saturday or Sunday there. circles_list names each circle's id. Any of the person's own accounts needing reconnection is named under unread, another member's never. 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. | |
| circle | Yes | The circle's id, as circles_list names it. | |
| 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. |