> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List Projects
> Lists projects with optional filtering.
`Unary` ยท [`Projects`](/docs/api-reference/generated/project/overview)
Lists projects with optional filtering.
Use this method to:
* View all accessible projects
* Browse project configurations
* Monitor project status
### Examples
* List projects:
Shows all projects with pagination.
```yaml theme={null}
pagination:
pageSize: 20
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.ProjectService/ListProjects
```
Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.
## Request example
```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.ProjectService/ListProjects" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"pagination": {
"pageSize": 1
}
}'
```
```python Python theme={null}
import gitpod.v1.pagination_pb2 as pagination_pb2
import gitpod.v1.project_pb2 as project_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = project_pb2.ListProjectsRequest(
pagination=pagination_pb2.PaginationRequest(
page_size=1,
),
)
response = ona.services.project.list_projects(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListProjectsRequestSchema } from "@gitpod/sdk/gitpod/v1/project_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListProjectsRequestSchema, {
pagination: {
pageSize: 1,
},
});
const response = await ona.services.project.listProjects(request);
console.log(response);
}
main().catch(console.error);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
"connectrpc.com/connect"
"github.com/gitpod-io/gitpod-sdk-go/sdk"
gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)
func main() {
ona, err := sdk.NewFromEnv()
if err != nil {
log.Fatal(err)
}
request := connect.NewRequest(&gitpodpb.ListProjectsRequest{
Pagination: &gitpodpb.PaginationRequest{
PageSize: 1,
},
})
response, err := ona.Services.Project.ListProjects(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"pagination": {
"pageSize": 1
}
}
```
## Request
`gitpod.v1.ListProjectsRequest`
| Field | Type | Required | Description |
| ------------ | ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request) | No | pagination contains the pagination options for listing organizations |
| `filter` | [Filter](#type-gitpod-v1-list-projects-request-filter) | No | |
| `sort` | [Sort](#type-gitpod-v1-sort) | No | sort specifies the order of results. Defaults to popularity descending. Supported fields: - "id": Sort by project ID (UUID v7, effectively creation order). Produces a stable, deterministic result set suitable for consistent pagination. - "popularity": Sort by popularity - a precomputed score based on recent environment creation activity. Updated periodically by a background job. |
| `count` | [CountRequest](#type-gitpod-v1-count-request) | No | count controls whether the response includes a bounded total count. |
## Response
`gitpod.v1.ListProjectsResponse`
| Field | Type | Required | Description |
| ------------ | --------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | pagination contains the pagination options for listing organizations |
| `projects` | array of [Project](#type-gitpod-v1-project) | No | |
| `count` | [CountResponse](#type-gitpod-v1-count-response) | No | count is the bounded total count of matching projects, present only when requested via CountRequest.include on the first page. |
## Related types
CountRequest controls whether the response should include a bounded
count of matching records.
`gitpod.v1.CountRequest`
| Field | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | boolean | No | When true, the first page of results will include a CountResponse with the bounded total. Subsequent pages (requests with a pagination token) will not contain the count. |
CountResponse represents a bounded count of matching records.
When the actual count exceeds the counting limit, value is capped and
relation is set to GREATER\_THAN\_OR\_EQUAL.
`gitpod.v1.CountResponse`
| Field | Type | Required | Description |
| ---------- | ---------------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
| `value` | integer | No | The count of matching records, capped at the server's counting limit. |
| `relation` | [CountResponseRelation](#enum-gitpod-v1-count-response-relation) | No | Indicates whether value is the exact total or a lower bound. |
EnvironmentInitializer specifies how an environment is to be initialized
`gitpod.v1.EnvironmentInitializer`
| Field | Type | Required | Description |
| ------- | ------------- | -------- | ----------- |
| `specs` | array of Spec | No | |
`gitpod.v1.ListProjectsRequest.Filter`
| Field | Type | Required | Description |
| ---------------- | -------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectIds` | array of string | No | project\_ids filters the response to only projects with these IDs Constraints: `repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0`. |
| `search` | string | No | search performs case-insensitive search across project name, project ID, and repository name Constraints: `string.max_len=256, string.min_len=0`. |
| `runnerIds` | array of string | No | runner\_ids filters the response to only projects that use environment classes from these runners Constraints: `repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0`. |
| `runnerKinds` | array of [RunnerKind](#enum-gitpod-v1-runner-kind) | No | runner\_kinds filters the response to only projects that use environment classes from runners of these kinds Constraints: `repeated.items.enum.defined_only=true, repeated.max_items=25, repeated.min_items=0`. |
| `specRemoteUris` | array of string | No | spec\_remote\_uris filters the response to only projects whose initializer spec remote URI matches any of the provided URIs (exact match) Constraints: `repeated.items.string.uri=true, repeated.max_items=25, repeated.min_items=0`. |
| `creatorIds` | array of string | No | creator\_ids filters the response to only projects whose creator ID matches any of the provided IDs Constraints: `repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0`. |
`gitpod.v1.PaginationRequest`
| Field | Type | Required | Description |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `pageSize` | integer | No | Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. Constraints: `int32.gte=0, int32.lte=100`. |
| `token` | string | No | Token for the next set of results that was returned as next\_token of a PaginationResponse |
`gitpod.v1.PaginationResponse`
| Field | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `nextToken` | string | No | Token passed for retrieving the next set of results. Empty if there are no more results |
`gitpod.v1.Project`
| Field | Type | Required | Description |
| ----------------------- | ------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | No | id is the unique identifier for the project Constraints: `string.uuid=true`. |
| `metadata` | [ProjectMetadata](#type-gitpod-v1-project-metadata) | No | |
| `initializer` | [EnvironmentInitializer](#type-gitpod-v1-environment-initializer) | No | initializer is the content initializer |
| `environmentClass` | [ProjectEnvironmentClass](#type-gitpod-v1-project-environment-class) | Yes | **Deprecated.** Use `environment_classes` instead. Constraints: `required=true`. |
| `devcontainerFilePath` | string | No | devcontainer\_file\_path is the path to the devcontainer file relative to the repo root |
| `environmentClasses` | array of [ProjectEnvironmentClass](#type-gitpod-v1-project-environment-class) | No | environment\_classes is the list of environment classes for the project |
| `usedBy` | [UsedBy](#type-gitpod-v1-project-used-by) | No | |
| `automationsFilePath` | string | No | automations\_file\_path is the path to the automations file relative to the repo root |
| `technicalDescription` | string | No | technical\_description is a detailed technical description of the project This field is not returned by default in GetProject or ListProjects responses |
| `prebuildConfiguration` | [ProjectPrebuildConfiguration](#type-gitpod-v1-project-prebuild-configuration) | No | prebuild\_configuration defines how prebuilds are created for this project. |
| `desiredPhase` | [ProjectPhase](#enum-gitpod-v1-project-phase) | No | desired\_phase is the desired phase of the project When set to DELETED, the project is pending deletion |
| `recommendedEditors` | [RecommendedEditors](#type-gitpod-v1-recommended-editors) | No | recommended\_editors specifies the editors recommended for this project. |
`gitpod.v1.Project.UsedBy`
| Field | Type | Required | Description |
| --------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------- |
| `subjects` | array of Subject | No | Subjects are the 10 most recent subjects who have used the project to create an environment |
| `totalSubjects` | integer | No | Total number of unique subjects who have used the project |
`gitpod.v1.ProjectEnvironmentClass`
| Field | Type | Required | Description |
| -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `localRunner` | boolean | No | Use a local runner for the user |
| `environmentClassId` | string | No | Use a fixed environment class on a given Runner. This cannot be a local runner's environment class. Constraints: `string.uuid=true`. |
| `order` | integer | No | order is the priority of this entry |
`gitpod.v1.ProjectMetadata`
| Field | Type | Required | Description |
| ---------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `organizationId` | string | No | organization\_id is the ID of the organization that contains the environment Constraints: `string.uuid=true`. |
| `name` | string | No | name is the human readable name of the project Constraints: `string.max_len=80, string.min_len=1`. |
| `creator` | Subject | No | creator is the identity of the project creator |
| `createdAt` | RFC 3339 timestamp | No | |
| `updatedAt` | RFC 3339 timestamp | No | |
ProjectPrebuildConfiguration defines how prebuilds are created for a project.
Prebuilds create environment snapshots that enable faster environment startup times.
`gitpod.v1.ProjectPrebuildConfiguration`
| Field | Type | Required | Description |
| ----------------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | No | enabled controls whether prebuilds are created for this project. When disabled, no automatic prebuilds will be triggered. |
| `environmentClassIds` | array of string | No | environment\_class\_ids specifies which environment classes should have prebuilds created. If empty, no prebuilds are created. Constraints: `repeated.items.string.uuid=true`. |
| `timeout` | duration string | No | timeout is the maximum duration allowed for a prebuild to complete. If not specified, defaults to 1 hour. Must be between 5 minutes and 2 hours. Constraints: `duration.gte.seconds=300, duration.lte.seconds=7200`. |
| `trigger` | PrebuildTrigger | No | trigger defines when prebuilds should be created. |
| `executor` | Subject | No | executor specifies who runs prebuilds for this project. The executor's SCM credentials are used to clone the repository. If not set, defaults to the project creator. |
| `enableJetbrainsWarmup` | boolean | No | enable\_jetbrains\_warmup controls whether JetBrains IDE warmup runs during prebuilds. |
RecommendedEditors contains the map of recommended editors and their versions.
`gitpod.v1.RecommendedEditors`
| Field | Type | Required | Description |
| --------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `editors` | map of string to EditorVersions | No | editors maps editor aliases to their recommended versions. Key is the editor alias (e.g., "intellij", "goland", "vscode"). Value contains the list of recommended versions for that editor. If versions list is empty, all available versions are recommended. Example: \{"intellij": \{versions: \["2025.1", "2024.3"]}, "goland": \{}} |
`gitpod.v1.Sort`
| Field | Type | Required | Description |
| ------- | --------------------------------------- | -------- | ------------------------------------ |
| `field` | string | No | Field name to sort by, in camelCase. |
| `order` | [SortOrder](#enum-gitpod-v1-sort-order) | No | |
| Value | Number | Description |
| ------------------------------------- | -----: | ---------------------------------------------------------------------------- |
| `COUNT_RESPONSE_RELATION_UNSPECIFIED` | 0 | |
| `COUNT_RESPONSE_RELATION_EQ` | 1 | The count is equal to the number of matching records. |
| `COUNT_RESPONSE_RELATION_GTE` | 2 | The actual number of matching records is greater than or equal to the value. |
| Value | Number | Description |
| --------------------------- | -----: | --------------------------------------------------------------------- |
| `PROJECT_PHASE_UNSPECIFIED` | 0 | |
| `PROJECT_PHASE_ACTIVE` | 1 | The project is active and can be used |
| `PROJECT_PHASE_DELETED` | 2 | The project is marked for deletion and prebuilds are being cleaned up |
RunnerKind represents the kind of a runner
| Value | Number | Description |
| --------------------------------- | -----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RUNNER_KIND_UNSPECIFIED` | 0 | Default zero value. Do not set explicitly. |
| `RUNNER_KIND_LOCAL` | 1 | **Deprecated.** Deprecated: Local runners are no longer supported. Use RUNNER\_PROVIDER\_AWS\_EC2 or RUNNER\_PROVIDER\_GCP instead. |
| `RUNNER_KIND_REMOTE` | 2 | The runner is a remote runner |
| `RUNNER_KIND_LOCAL_CONFIGURATION` | 3 | The runner is a system-managed runner that holds shared configuration for local runners. Every organization automatically has one of these runners, and it cannot be deleted nor can new runners of this kind be created. Organization admins can update this runner to change the shared configuration, including: - SCM Integrations. All local runners will use these integrations. - DesiredPhase. Can be set to STOPPED to disable all local runners. This runner cannot be used to run environments. |
| Value | Number | Description |
| ------------------------ | -----: | ----------- |
| `SORT_ORDER_UNSPECIFIED` | 0 | |
| `SORT_ORDER_ASC` | 1 | |
| `SORT_ORDER_DESC` | 2 | |