Run a saved query
run_queryRuns a saved OpenProject view and returns its work packages, preserving the team's stored filters, grouping, and sorting.
Instructions
Run a saved view and get its work packages — the fastest way to answer with a team's own definition of "the sprint" or "our bugs".
OpenProject queries run on read: this returns the rows as they are right now, in the
stored order and grouping. The result is the standard list envelope — items of
compact work-package rows, pagination, plus groups when the query groups and
sums when it asks for totals — with one addition: query carries the stored
definition (name, project, readable filters, group_by, sort_by), so the rows
can be interpreted without a second call.
Pitfalls. groups and sums are computed server-side across the entire result set,
not the page in front of you — never re-add them from items. Omitting page_size
keeps the query's own page size, which may be much larger than 20. override_filters
replaces the stored filters instead of narrowing them, and never edits the saved
query. A 422 means the filter set is invalid for this query's context (a
project-scoped filter on a global query, an unknown custom field); violations names
the attribute.
Cross-references: find query ids with list_queries; equivalent ad-hoc filtering
lives in list_work_packages; open a single row with get_work_package.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. Omit to use the page the stored query starts on (the first). | |
| query_id | Yes | Saved query id, from list_queries. It is the same id as in the UI's ?query_id= URL parameter. | |
| page_size | No | Rows per page (max 100). Omit to keep the query's stored page size, which can be larger or smaller than this tool's usual default. | |
| override_filters | No | Run the query with these filters instead of its stored ones, for this call only — e.g. [{'name': 'status', 'operator': 'o', 'values': []}] or [{'name': 'customField12', 'operator': '=', 'values': ['4']}]. This REPLACES the stored filters (the API cannot merge), so re-state anything you want to keep; 'query.filters' in the result shows what the stored ones were. |
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, … | |
| query | Yes | The stored query definition, so the rows can be interpreted. | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |