List work packages
list_work_packagesQuery and filter OpenProject work packages by assignee, status, due date, project, or custom fields; returns paginated rows with optional groups and server-computed sums.
Instructions
List work packages with structured filters — the workhorse read tool.
Handles "assigned to me", "overdue" via parameters, 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: rows plus pagination, plus groups when
group_by is set and sums when show_sums is set — both computed server-side over
the whole filtered set, independent of paging; never re-add them from one page's rows.
Pitfalls: returns open work packages only unless status_scope or status_ids is
given (status_ids overrides status_scope), so say so when reporting counts. Status,
type, priority and version ids come from get_project_metadata; user ids (assignee,
author, responsible, watcher) from search_principals — never guess either. Date
filters take YYYY-MM-DD.
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 | Free text, AND-combined with other filters; matches subject, description and comments. | |
| author | No | Author (creator) user ids, or 'me' ('none' not valid). | |
| project | No | Numeric project id or identifier (URL slug); from list_projects. Omit for a cross-project view. | |
| sort_by | No | Sort as snake_case pairs, e.g. [['due_date','asc'],['priority','desc']]. An unknown key fails, listing the allowed set. | |
| watcher | No | Watched by these user ids, or 'me'. | |
| assignee | No | Assignee filter: numeric user ids, 'me', or 'none' for unassigned work. get_instance_info gives the current user. | |
| group_by | No | Group the full filtered set by one snake_case column (e.g. 'status'). Counts in `groups` cover every page. | |
| type_ids | No | Type ids (Task, Bug…). | |
| due_after | No | Due on/after, ISO date. | |
| fetch_all | No | Aggregate every page into one result instead of page 1. Capped at 500 items (noted when it bites); mutually exclusive with page. | |
| page_size | No | Results per page (max 100). | |
| parent_id | No | Direct children only. Mutually exclusive with top_level_only; use ancestor_id for the whole subtree. | |
| show_sums | No | Server-computed totals (estimated/remaining/spent hours, story points) over the full filtered set; never add up pages yourself. | |
| due_before | No | Due on/before, ISO date. | |
| sprint_ids | No | Sprint ids; from list_sprints. | |
| status_ids | No | Exact status ids. **Overrides status_scope**. | |
| ancestor_id | No | Whole subtree, any depth (parent_id is one level only). | |
| raw_filters | No | Escape hatch for untyped filters, e.g. custom fields: [{'name': 'customField12', 'operator': '=', 'values': ['4']}]. Field names and option ids come from get_work_package_schema. | |
| responsible | No | Accountable user ids, 'me', or 'none' (no accountable user). | |
| start_after | No | Starts on/after, ISO date. | |
| version_ids | No | Version ids. | |
| priority_ids | No | Priority ids. | |
| start_before | No | Starts on/before, ISO date. | |
| status_scope | No | Status bucket: 'open' (default), 'closed' or 'all'. Ignored when status_ids is given. | open |
| created_since | No | Created on/after, ISO date. | |
| updated_since | No | Changed on/after, ISO date. | |
| top_level_only | No | Work packages with no parent (excludes every subtask). | |
| milestones_only | No | Only milestone-type work packages; intersected with type_ids when both are given. | |
| percentage_done_max | No | Maximum progress percent. | |
| percentage_done_min | No | Minimum progress percent. |
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. |