Method: projects.list

Lists Projects that the caller has the resourcemanager.projects.get permission on and satisfy the specified filter.

This method returns Projects in an unspecified order. This method is eventually consistent with project mutations; this means that a newly created project may not appear in the results or recent updates to an existing project may not be reflected in the results. To retrieve the latest state of a project, use the [projects.get][Projects.GetProject] method.

NOTE: If the request filter contains a parent.type and parent.id and the caller has the resourcemanager.projects.list permission on the parent, the results will be drawn from an alternate index which provides more consistent results. In future versions of this API, this List method will be split into List and Search to properly capture the behavorial difference.

HTTP request

Query parameters

A pagination token returned from a previous call to projects.list that indicates from where listing should continue.

Optional.

pageSize

number

The maximum number of Projects to return in the response. The server can return fewer Projects than requested. If unspecified, server picks an appropriate default.

Optional.

filter

string

An expression for filtering the results of the request. Filter rules are case insensitive. The fields eligible for filtering are:

name

id

labels.<key> (where key is the name of a label)

parent.type

parent.id

Some examples of using labels as filters:

Filter

Description

name:how*

The project's name starts with "how".

name:Howl

The project's name is Howl or howl.

name:HOWL

Equivalent to above.

NAME:howl

Equivalent to above.

labels.color:*

The project has the label color.

labels.color:red

The project's label color has the value red.

labels.color:red labels.size:big

The project's label color has

the value red and its label size has the value big.

If no filter is specified, the call will return projects for which the user has the resourcemanager.projects.get permission.

NOTE: To perform a by-parent query (eg., what projects are directly in a Folder), the caller must have the resourcemanager.projects.list permission on the parent and the filter must contain both a parent.type and a parent.id restriction (example: "parent.type:folder parent.id:123"). In this case an alternate search index is used which provides more consistent results.

Optional.

Request body

The request body must be empty.

Response body

If successful, the response body contains data with the following structure:

The list of Projects that matched the list filter. This list can be paginated.

nextPageToken

string

Pagination token.

If the result set is too large to fit in a single response, this token is returned. It encodes the position of the current result cursor. Feeding this value into a new list request with the pageToken parameter gives the next page of the results.

When nextPageToken is not filled in, there is no next page and the list returned is the last page in the result set.