List projects
list_projectsFetch OpenProject projects page by page with filters for search, parent, and phase. Converts project names to IDs, lists sub-projects, and flags off-track status.
Instructions
List projects, filtered server-side, one page at a time.
Use this to turn a project name into the id or identifier that every other tool
consumes, to enumerate the sub-projects of a parent, or to review which projects are
off track. It is the id-producing path for every project_id parameter in this
server.
Returns the standard list envelope: items of
{id, identifier, name, active, public, parent, status_code, workspace_type} plus
pagination with total/page/page_size/has_more. Nothing is
truncated silently — page explicitly until has_more is false.
Pitfalls: search matches name and identifier only (not descriptions);
parent_id returns direct children, so a deep hierarchy needs one call per level;
status_code is a code such as on_track, never a translated label. On
OpenProject 17.x this listing deliberately mixes plain projects with programs and
portfolios — workspace_type says which each row is. in_phase tests phase
dates ("which projects are in Executing today"), so projects whose phases carry
no dates never match it.
For a single project's description and status explanation use get_project. For
the types, versions, categories and time-entry activities valid inside a project use
get_project_metadata. To list a project's work packages use
list_work_packages(project=...).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| active | No | true (default) lists active projects, false lists only archived ones, null lists both. Archived projects are read-only in OpenProject. | |
| search | No | Case-insensitive substring matched against the project name AND its identifier. Descriptions are not searched. Omit to list everything the filters allow. | |
| sort_by | No | Server-side sort, e.g. [["name", "asc"], ["created_at", "desc"]]. Allowed keys: active, created_at, id, identifier, name, public, updated_at. Unknown keys are rejected with the allowed set listed. | |
| in_phase | No | Restrict to projects whose named phase covers a date (today unless phase_on_date says otherwise). Accepts a definition id or name from list_project_phase_definitions. Requires OpenProject 16.1+. | |
| 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 | Records per page (max 100); the instance may clamp it lower and the returned pagination reports what actually came back. | |
| parent_id | No | Numeric id or identifier of a parent project; returns its DIRECT children only, not the whole subtree. Ids come from a previous list_projects call. | |
| phase_on_date | No | ISO date (YYYY-MM-DD) the in_phase filter should test instead of today. Only valid together with in_phase. | |
| favorites_only | No | Restrict to projects the authenticated user has favorited. Instances that predate project favorites reject this filter with a 400. |
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. |