forecast_get
Retrieve forecast-view tasks from OmniFocus, grouped by overdue, due today, deferred today, and flagged. Plan your day or week by specifying a date and number of days.
Instructions
Get forecast-view tasks from OmniFocus grouped by category: overdue, dueToday, deferredToday, flagged. Use this for 'what's on my plate today' or multi-day planning queries. Do NOT use to list all tasks across all projects; prefer task_list instead. Supply date (ISO-8601 or shortcut like 'today', 'tomorrow') and days (1–7) for the ergonomic interface, or use from/to for exact ISO-8601 ranges. All include flags default to true; set to false to omit a category. When days > 1, response also includes byDate[] grouping task IDs per calendar day (dereference from dueToday[]). Returns { overdue[], dueToday[], deferredToday[], flagged[], byDate? } plus pagination { hasMore, cursor }; byDate entries are { date, taskIds[] }. Pages span the union of all four buckets (a task in multiple buckets counts once); default 50 tasks per page (max 200). Safe to call repeatedly; no side effects. Example: forecast_get({ date: "today" }) Example: forecast_get({ date: "today", days: 3, includeFlagged: false }) Example: forecast_get({ date: "today", limit: 25, cursor: "" })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of date range (ISO-8601 or relative shortcut like 'today'). Use date/days for the ergonomic interface instead. Defaults to end of today. | |
| date | No | Anchor date for the forecast (ISO-8601 or relative shortcut: today, tomorrow, yesterday, this-week, next-week). Mutually exclusive with from/to. Defaults to today. | |
| days | No | Number of days to cover (1–7). Default 1. When > 1, byDate[] is included in the response. | |
| from | No | Start of date range (ISO-8601 or relative shortcut like 'today'). Use date/days for the ergonomic interface instead. Defaults to start of today. | |
| limit | No | Max unique tasks per page (1..200). Default 50. Pagination spans the union of overdue/dueToday/deferredToday/flagged: a task that appears in multiple buckets counts once. Use `cursor` to fetch subsequent pages. | |
| cursor | No | Opaque cursor from a previous forecast_get response. Must use the same filters (date/from/to/days/include* /fields) — changing filters mid-sequence returns a ValidationError. | |
| fields | No | Restrict each returned task (across overdue/dueToday/deferredToday/flagged/byDate) to this list of top-level fields (id is always returned). Omit for the full task shape. Empty array returns just id. Unknown names are dropped silently and surface in meta.warnings.WARN_UNKNOWN_FIELDS. Allowed: name, note, noteHtml, projectId, parentId, tagIds, deferDate, deferDateFloating, dueDate, dueDateFloating, estimatedMinutes, flagged, completed, completedAt, dropped, droppedAt, available, blocked, sequential, completedByChildren, repetition, notifications, createdAt, modifiedAt, _links. | |
| includeFlagged | No | Include all flagged incomplete tasks. Default true. | |
| includeOverdue | No | Include tasks overdue before the start of the range. Default true. | |
| maxOutputBytes | No | Cap the serialized byte size of the forecast payload (the overdue/dueToday/deferredToday/flagged/byDate buckets together). When the page would exceed this, the server keeps as many whole tasks as fit, sets meta.truncatedAtCap=true with meta.bytesReturned and meta.itemsReturned, and returns a pagination cursor that resumes at the first dropped task. Omit for no cap. Values above the server's hard ceiling (~1 MiB) are clamped. A single task larger than the cap is still returned whole so pagination always advances. | |
| includeDeferred | No | Include tasks whose defer date falls within the range. Default true. |