List work packages
list_work_packagesList work packages with structured filters for assigned, overdue, sprint, and progress queries. Get paginated results with server-side grouping and sums.
Instructions
List work packages with structured filters — the workhorse read tool.
Use it for every "what is assigned to me", "what is overdue", "what is in this sprint"
question. Convenience queries are parameters here, not separate tools: overdue →
due_before=<today>; unassigned → assignee=['none']; nearly done →
percentage_done_min=80; subtasks of a ticket → parent_id=<id>.
Returns the standard list envelope: compact rows plus pagination, plus groups when
group_by was requested and sums when show_sums was requested. Groups and sums are
computed server-side over the whole filtered set, independent of paging — never re-add
them from the rows on one page.
Pitfalls: this returns open work packages only unless you pass status_scope or
status_ids, so say so when you report counts. status_ids overrides status_scope.
Status, type, priority and version ids differ per instance and must come from
get_project_metadata, never from memory.
For text lookups use search_work_packages; for one work package's description, custom
fields and children use get_work_package.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| query | No | Optional free text, AND-combined with every other filter. Matches subject, description and comments. For text-only lookups prefer search_work_packages. | |
| author | No | Author (creator) user ids, or 'me'. 'none' is not valid here. | |
| project | No | Numeric project id or project identifier (URL slug) to scope the query. Both come from list_projects. Omit for a cross-project view. | |
| sort_by | No | Server-side sort as snake_case pairs, e.g. [['due_date','asc'],['priority','desc']]. An unknown key fails with the allowed set listed. | |
| watcher | No | Work packages watched by these user ids, or 'me'. | |
| assignee | No | Assignee filter: numeric user ids, the single value 'me', or the single value 'none' for unassigned work. Ids come from search_principals; get_instance_info gives the current user. | |
| group_by | No | Group the full filtered set by one snake_case column (e.g. 'status', 'assignee'). Counts in `groups` cover every page, not just this one. | |
| type_ids | No | Work package type ids (Task, Bug…); from get_project_metadata. | |
| due_after | No | Due on or after this ISO date (YYYY-MM-DD). | |
| fetch_all | No | Aggregate every page into one result instead of returning page 1. Capped at 500 items with a note when the cap bites; mutually exclusive with page. | |
| page_size | No | Results per page (max 100). | |
| parent_id | No | Direct children of this work package only. Mutually exclusive with top_level_only; use ancestor_id for the whole subtree. | |
| show_sums | No | Ask the server for totals (estimated/remaining/spent hours, story points) over the full filtered set. Never add up pages yourself. | |
| due_before | No | Due on or before this ISO date (YYYY-MM-DD). | |
| status_ids | No | Exact status ids. **Overrides status_scope** — the two never fight. Ids come from get_project_metadata. | |
| ancestor_id | No | Everything in this work package's subtree at any depth, unlike parent_id which is one level only. | |
| raw_filters | No | Escape hatch for filters this tool does not type, most importantly custom fields: [{'name': 'customField12', 'operator': '=', 'values': ['4']}]. Custom field names and option ids come from get_work_package_schema. | |
| responsible | No | Accountable user ids, 'me', or 'none' for no accountable user. | |
| start_after | No | Starts on or after this ISO date (YYYY-MM-DD). | |
| version_ids | No | Version / sprint ids; from get_project_metadata. | |
| priority_ids | No | Priority ids; from get_project_metadata. Never guess these — priority ids differ per instance. | |
| start_before | No | Starts on or before this ISO date (YYYY-MM-DD). | |
| status_scope | No | Status bucket: 'open' (default), 'closed' or 'all'. An explicit status filter is always sent, so the server's implicit open-only default never silently applies. Ignored when status_ids is given. | open |
| created_since | No | Created on or after this ISO date (YYYY-MM-DD). | |
| updated_since | No | Last changed on or after this ISO date (YYYY-MM-DD). | |
| top_level_only | No | Only work packages that have no parent. Excludes every subtask. | |
| milestones_only | No | Only milestone-type work packages. Resolved against this instance's own types (no hardcoded ids) and intersected with type_ids when both are given. | |
| percentage_done_max | No | Maximum progress percentage, 0-100. | |
| percentage_done_min | No | Minimum progress percentage, 0-100. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sums | No | Present only when show_sums was requested. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |