project_list
List OmniFocus projects using filters for status, folder, flagged, or review due date.
Instructions
List projects in OmniFocus with optional filters. Use for queries across projects. Do NOT use for a known single project (use project_get). Filters: folderId, status, flagged, reviewDueBefore. Returns projects[] with pagination; safe to call repeatedly; no side effects. Example: project_list({}) Example: project_list({ status: "active", folderId: "fld123" })
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max projects per page (1..1000). Default 50. Use `cursor` to fetch subsequent pages. | |
| cursor | No | Opaque cursor from a previous project_list response. Must use the same filters — changing filters mid-sequence returns a ValidationError. | |
| fields | No | Restrict each returned project to this list of top-level fields (id is always returned). Omit for the full project shape. Empty array returns just id. Unknown names surface in meta.warnings.WARN_UNKNOWN_FIELDS. | |
| status | No | Restrict to projects with this status. 'active' = available; 'on-hold' = paused; 'done' = completed; 'dropped' = abandoned. Omit for any status. Accepts: 'paused' → on-hold, 'completed' → done, 'cancelled' → dropped. | |
| flagged | No | true = flagged only; false = unflagged only; omit = both. | |
| verbose | No | When true, return the full unelided project shape. Default: false — fields equal to their documented default (status: 'active', completionCriterion: 'parallel', flagged: false, tagIds: [], note: null, etc.) are omitted. See docs/token-cost.md for the defaults table. | |
| folderId | No | Restrict to projects inside this folder. Get the ID from folder_list. Omit for all folders. | |
| includeLinks | No | When true, each project carries a `_links` HATEOAS block (self, folder). Default false — the block is omitted to save payload size. Use the project's `id` and `folderId` fields directly instead. | |
| maxOutputBytes | No | Cap the serialized byte size of the returned projects[] array. When the response would exceed this, the server returns as many whole projects as fit, sets meta.truncatedAtCap=true with meta.bytesReturned and meta.itemsReturned, and returns a pagination cursor that resumes at the first dropped project. Omit for no cap. Values above the server's hard ceiling (~1 MiB) are clamped. A single project larger than the cap is still returned whole so pagination always advances. | |
| reviewDueBefore | No | Restrict to projects whose next review date is strictly before this moment. ISO-8601 with offset (e.g. '2026-05-01T00:00:00-07:00'). Projects without a review interval are excluded. |