Get schedule
get_scheduleRead the calendar: the agenda, what is on, how busy the user is, free time, or where the time goes. One call returns the current local time (now, "YYYY-MM-DDTHH:MM"), the user's timezone, the user's areas, activityTypes and projects (the lookup lists for areaId / activityTypeId / projectId; a project has an areaId; an archived project has archived: true, refuses new links, and comes back with a manage_categories update archived: false), userPreferences, and a days array. Each day has its events, its freeSlots, and its blocking load per area, activity type and project (projectId null is no project; non-blocking overlay load comes separately). A read of more than one day also has a top-level loadByProject, the sum of its days (for example, a week). Call it before you schedule, to anchor relative times ('this afternoon'). Pass from and to (ISO YYYY-MM-DD, inclusive; equal for one day). Pass includeSeries: true to also get the recurring series as series (the live ones and the ones in the range, with no notes). Pass includeLookups: false on a later call to leave out areas, activityTypes, projects and integrations.
Time spans: every event and free slot is start + end, two local datetimes "YYYY-MM-DDTHH:MM" in the top-level timezone (e.g. start "2026-09-23T22:00", end "2026-09-24T01:00"). The end is always after the start; a slot to midnight ends at the next day's T00:00. An event from an earlier day that runs into this day is listed first, with its real start, on every day that it touches; only its time inside the day counts for load and free slots. A warning marks a start time that a DST change skips.
Each event carries its source ("reassign", else a provider like "google"), its home calendarId (absent = the default calendar, null = dial only) and any mirrorCalendarIds (with mirrorStyles when a copy is private or busy). An event with readOnly: true is on a calendar the user does not own: do not edit or delete it (tell them to change it there). kind "non_blocking" is an overlay that may overlap others (fasting, an away marker); "reference" is see-only: its hours stay free, so do not move, delete, or schedule work into it unless asked. A confirmed past day carries a review adherence rollup and per-event reflect actuals; use them for how a day or week actually went. When a calendar is connected, integrations describes it (a calendar's timezone is information only; every span uses the top-level timezone; a calendar's copyStyle applies to copies when mirrorStyles omits that calendar). For a single day, a one-line weather headline is included when the user has a city. For one day, pass includeWeather: true for the full forecast (an outdoor plan only) and includeEnergy: true for the energy curve (energy: peak and dip windows from logged sleep), to put focus work in a peak.
Inbox: backlogCount is the number of Inbox blocks (un-timed intentions). Pass includeBacklog: true for the items (top of tray first, up to 50); backlogPlannedOn, backlogProjectId (an id or "none"), backlogMinPriority (0 to 4) and backlogOffset filter or page them and need includeBacklog: true; with a filter, backlogMatchedCount is the number of matches. Each item has a projectId and a priority (0 none, 1 low, 2 medium, 3 high, 4 urgent). To find an item by name, use find_event. When nextBacklogOffset is not null, pass it as backlogOffset with the same filters for the next page. Place or manage items with manage_inbox.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Last day of the range, inclusive. | |
| from | Yes | First day of the range, inclusive. | |
| minDuration | No | Return only the `freeSlots` of at least this many minutes. | |
| backlogOffset | No | Inbox page offset from nextBacklogOffset; keep the same filters. Needs includeBacklog: true. | |
| includeEnergy | No | Add `energy`: the user's forecast energy curve for the day (peak and dip windows, the current level today, calibration state), built from logged sleep. Use it to put focus work in a peak and admin in a dip. With no logged sleep it is a short nudge to log sleep. Needs one day (`from` equal to `to`). | |
| includeSeries | No | Also return the recurring masters as `series`. | |
| includeBacklog | No | Include the Inbox items (the `backlog` array), not just `backlogCount`. Pass true when the user wants to see, schedule, or manage their Inbox. | |
| includeLookups | No | Default true. Pass false to leave out `areas`, `activityTypes`, `projects` and `integrations` when you already have them from an earlier read. | |
| includeWeather | No | Replace the one-line `weather` headline with the full forecast for the day (condition, temperature range, rain window, daylight, and a part-of-day breakdown). Use it only for an outdoor or weather-sensitive plan, or when the user asks about the weather. Needs one day (`from` equal to `to`). | |
| weatherLocation | No | A city or place name to forecast instead of the user's own city, e.g. "London". The forecast date and times are local to that place; the report names its timezone. Needs includeWeather: true. | |
| backlogPlannedOn | No | Filter the Inbox blocks to those planned for this day (a planned day, or a planned window that covers it). Needs includeBacklog: true. | |
| backlogProjectId | No | Filter the Inbox blocks to one project id, or "none" for the blocks with no project. Needs includeBacklog: true; composes with the other filters. | |
| backlogMinPriority | No | Filter the Inbox blocks to a priority of at least this value (0 none, 1 low, 2 medium, 3 high, 4 urgent). Needs includeBacklog: true; composes with the other filters. |