task_search
Search OmniFocus tasks by keyword or filters. Narrow results with project, tags, due dates, availability, and pagination.
Instructions
Search OmniFocus tasks by keyword and/or structured filters, with cursor pagination. q is optional — omit it to filter by tag, project, date range, or availability alone. When q is supplied, scans task names and/or notes (controlled by scope) for a case-insensitive substring match. Narrow results with: projectId, tagIds (task must carry ALL listed tags), available, dueBefore, dueAfter, flagged, and completed. At least one of q, projectId, tagIds, available, dueBefore, or dueAfter must be provided. Do NOT use when you already have an ID — prefer task_get instead. Returns tasks[] with pagination (limit defaults to 50, max 500); safe to call repeatedly; no side effects. Example: task_search({ q: "dentist" }) Example: task_search({ tagIds: ["tag123"], available: true, dueBefore: "2026-05-01T00:00:00Z" })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search query. Case-insensitive substring match applied to the fields in scope. Optional — omit to filter by tags, project, date range, or availability alone. | |
| limit | No | Max results per page (1..500). Default 50. Use cursor to fetch subsequent pages. | |
| scope | No | 'name' = search task name only; 'note' = search note only; 'all' = both (default). Ignored when q is omitted. | |
| cursor | No | Opaque cursor from a previous task_search response. Must use the same filters — changing filters mid-sequence returns a ValidationError. | |
| tagIds | No | Restrict to tasks carrying ALL of these tag IDs. | |
| flagged | No | true = flagged tasks only; false = unflagged only; omit = all. | |
| dueAfter | No | Tasks with dueDate strictly after this moment. ISO-8601 with offset or relative shortcut. | |
| available | No | true = only tasks available to work on now (not blocked, not deferred, not completed). Omit = all. | |
| completed | No | 'exclude' = active tasks only (default); 'only' = completed tasks only; 'any' = both. | |
| dueBefore | No | Tasks with dueDate strictly before this moment. ISO-8601 with offset or relative shortcut. | |
| projectId | No | Restrict search to tasks within this project. | |
| 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. |