ListCalendarEventsCopy Anchor Link

List the user's calendar events between two instants, across every calendar they have connected. Returns one entry per occurrence (a recurring event appears once per instance in the window), soonest first, with the eventId needed by UpdateCalendarEvent and DeleteCalendarEvent.

Use this to answer questions about the user's schedule ("what's on my calendar tomorrow?"), to find an event the user wants changed or removed, and to check for conflicts before creating an event. Keep the window as narrow as the request allows — a day or a week — since wide windows truncate at 200 occurrences. The window must be at most 370 days and within one year past to two years future. If syncStatus is syncing, tell the user results may still be incomplete.

The user can see calendars that are not theirs, such as a colleague's or a team's. inbox is the account syncing a calendar, so it stays the user's own address on all of them, and neither it, isReadOnly nor myRole says whose calendar it is. Their schedule is the calendars with contributesToAvailability, plus meetings they attend: only those are "your calendar", and only those count as conflicts or busy time, as in GetTeamAvailability. Anything else is what that calendar shows, not where the user is or what they are doing. Call it by calendarName, say whose it is when the name shows that, and otherwise say you cannot tell rather than guess. When one overlaps a time you suggest, mention it so the user can decide, since their own other calendars read the same way.

Each entry names the calendar (calendarName) and connected inbox (inbox) holding that copy of the event, and myRole says whether the user organizes it or is a guest there. A meeting on several of the user's inboxes appears once per inbox, each with its own eventId, and what the user may do can differ between them. When asking which one the user means, describe each by its inbox and role, never by id; when the user names an inbox, act on the entry whose inbox matches.

When the user does not name an inbox, choose the copy by what the change does. Reminders belong to one copy only, so set them on one copy without asking and say which inbox you used. Answer an invitation on the copy where the user is a guest; when they are a guest through more than one inbox, ask which inbox answers, since each answers only for itself. Any other change reaches the meeting differently from each copy: the title, time, description, location, recurrence or conference, adding or removing guests, guest permissions, and deleting. UpdateCalendarEvent and DeleteCalendarEvent refuse such a change on a meeting held by several of the user's inboxes until inbox names the inbox of the copy being changed, and the refusal lists each copy. If only one copy allows the change (viewerCan, or for deleting, isReadOnly false), use that copy with its inbox and say why (for example, only the copy the user organizes can move the meeting). If more than one can, ask which inbox, saying what the change would do from each, and never choose between the user's inboxes yourself, whatever they look like. Add guests from the copy the user organizes when there is one: it invites them directly, while a guest's copy invites only as far as the organizer allows. Deleting the organizer's copy cancels the meeting for everyone, while deleting a guest's copy takes the meeting off that inbox's calendar and, on Google, also declines the invitation and tells the organizer.

ParametersCopy Anchor Link