list_tasks
Retrieve and filter project tasks with strict filters or search across workspaces by title/description; filter by status, priority, assignee, labels, or runtime state.
Instructions
List tasks with strict filters. Provide project_id for a project listing or workspace_id plus search for cross-project search. Unknown parameters and invalid categories are errors. Compact items contain id, title, status slug, priority, assignee_name, labels, updated_at, runtime_state (working/waiting/queued/stopped with since/lane/ref/stale, when known) and routing parent_task_id/start_after when set; workspace results also contain project_id. Pass full=true for complete REST items; listing descriptions are subject to the API page budget, so use get_task for guaranteed full details.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | Return complete items (full descriptions and non-capability envelope fields) instead of compact items. | |
| page | No | 1-based page number (default 1). The response reports total_pages; without this parameter every page beyond the first was unreachable while the envelope kept advertising them. | |
| sort | No | Sort field: created_at, updated_at, priority, due_date. | |
| limit | No | Max results to return (default 20). The compact view caps limit at 50 — a larger value is clamped and the response says so via limit_clamped_to; pass full=true for up to 200 per page. | |
| order | No | Sort direction: asc (default) or desc. Without this, a project larger than `limit` returns its OLDEST tasks, so "what changed recently" walks come back empty and look clean. An invalid value is REFUSED by the API, not silently treated as asc. | |
| labels | No | Filter by labels. | |
| search | No | Search in title and description. | |
| assignee | No | Filter by exact case-insensitive assignee name, UUID, or me. Unknown or ambiguous names are errors. | |
| priority | No | Filter by priority: urgent, high, medium, low, none. | |
| project_id | No | Project ID (required unless workspace_id is provided). | |
| assignee_id | No | UUID-only compatibility alias for assignee. Use assignee for names or me. | |
| runtime_kind | No | Filter by effective runtime state: working, waiting, queued, stopped. working also matches a card with a live checkout and no reported state, whatever its status. | |
| workspace_id | No | Workspace ID for global cross-project search (requires search parameter). | |
| assignee_type | No | Filter by assignee type: user, agent, unassigned. | |
| list_revision | No | The list_revision echoed back on a previous page of this same project-scoped walk (see the response's list_revision field). Pass it back to continue that walk. If the project's tasks changed since that page was issued, the call is REFUSED with list_revision_stale (HTTP 410) instead of silently returning an inconsistent page — restart pagination from page 1 (omit this field) on that error. Omit on the first page of a fresh walk. Ignored for workspace_id search. | |
| status_category | No | Filter by status category: backlog, todo, in_progress, review, done, cancelled. |