task_list
List tasks from OmniFocus with filters for project, tag, inbox, flagged, completion, and due dates to retrieve specific task sets.
Instructions
List tasks in OmniFocus with optional filters (project, tag, inbox, flagged, completion, due dates). Use inbox=true to fetch unprocessed Inbox tasks. Use this for filter-based queries across tasks. Do NOT use for a known single task (use task_get). For name-based lookup, prefer task_find_by_name. For full-text content search across names and notes, prefer search_query. Returns tasks[] with pagination; safe to call repeatedly; no side effects. Example: task_list({ inbox: true }) Example: task_list({ projectId: "prj123", flagged: true }) Example: task_list({ dueBefore: "2026-05-01T00:00:00Z", completed: "exclude" })
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| inbox | No | true = Inbox tasks only (no project assignment). Cannot be combined with projectId or parentId. Use this to surface unprocessed captures without knowing their IDs. | |
| limit | No | Max tasks per page (1..1000). Default 50. Use `cursor` to fetch subsequent pages. | |
| cursor | No | Opaque cursor from a previous task_list response. Must use the same filters — changing filters mid-sequence returns a ValidationError. | |
| fields | No | Restrict each returned task to this list of top-level fields (id is always returned). Omit for the full task shape. Empty array returns just id. Unknown names surface in meta.warnings.WARN_UNKNOWN_FIELDS. | |
| sortBy | No | Field to sort tasks by: 'createdAt' (default), 'dueDate', 'modifiedAt', or 'name'. Tasks with no value for the chosen field (e.g. no dueDate) sort last. | |
| tagIds | No | Restrict to tasks carrying ALL of these tag IDs. Get IDs from tag_list. | |
| flagged | No | true = flagged only; false = unflagged only; omit = all. | |
| verbose | No | When true, return the full unelided task shape (every field present, even at defaults). Default: false — fields equal to their documented default (flagged: false, completed: false, tagIds: [], note: null, dueDate: null, etc.) are omitted from the wire payload. An omitted field means the default applies. See docs/token-cost.md for the full defaults table. | |
| dueAfter | No | Tasks with dueDate strictly after this moment. ISO-8601 with offset. | |
| parentId | No | Restrict to direct children of this task (subtasks). Get the ID from task_get or task_list. | |
| available | No | true = only tasks available to work on now (not blocked, not deferred). Omit = all. | |
| completed | No | 'exclude' = active tasks only; 'only' = completed tasks only; 'any' = both. Omit for adapter default. | |
| dueBefore | No | Tasks with dueDate strictly before this moment. ISO-8601 with offset (e.g. '2026-04-21T17:00:00-04:00'). | |
| projectId | No | Restrict to tasks in this project. Get the ID from project_list. Omit for all projects. | |
| includeLinks | No | When true, each task carries a `_links` HATEOAS block (self, project, parent, tags). Default false — the block is omitted to save payload size. Use the task's `id`, `projectId`, `parentId`, and `tagIds` fields directly instead. | |
| updatedSince | No | Return only tasks modified strictly after this timestamp. Accepts ISO-8601 with offset (e.g. '2026-04-21T10:00:00-07:00') or a relative shortcut: today, yesterday, this-week, next-week, end-of-week, end-of-month. Use this for incremental sync: call without updatedSince on session start, then pass the previous response timestamp on subsequent calls. Note: deleted tasks cannot be detected — use a snapshot resource for deletion detection. | |
| sortDirection | No | Sort direction: 'asc' (default, oldest/lowest first) or 'desc' (newest/highest first). | |
| deferredBefore | No | Tasks deferred until before this moment (already unlocked or soon). ISO-8601 with offset. | |
| maxOutputBytes | No | Cap the serialized byte size of the returned tasks[] array. When the response would exceed this, the server returns 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. | |
| notePreviewChars | No | Maximum characters of each task's note to return. Default 200. When a note exceeds this length, the response replaces `note` with `notePreview` (the truncated text), `noteTruncated: true`, and `noteLength` (full UTF-8 byte length) — fetch the full text with note_get. Pass -1 to disable truncation and return full notes inline. |