> ## 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 Warm Pools
> Lists warm pools with optional filtering.
`Unary` ยท [`Prebuilds`](/docs/api-reference/generated/prebuild/overview)
Lists warm pools with optional filtering.
Use this method to:
* View all warm pools for a project
* Monitor warm pool status across environment classes
### Examples
* List warm pools for a project:
```yaml theme={null}
filter:
projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"]
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.PrebuildService/ListWarmPools
```
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.PrebuildService/ListWarmPools" \
--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.prebuild_pb2 as prebuild_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = prebuild_pb2.ListWarmPoolsRequest(
pagination=pagination_pb2.PaginationRequest(
page_size=1,
),
)
response = ona.services.prebuild.list_warm_pools(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListWarmPoolsRequestSchema } from "@gitpod/sdk/gitpod/v1/prebuild_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListWarmPoolsRequestSchema, {
pagination: {
pageSize: 1,
},
});
const response = await ona.services.prebuild.listWarmPools(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.ListWarmPoolsRequest{
Pagination: &gitpodpb.PaginationRequest{
PageSize: 1,
},
})
response, err := ona.Services.Prebuild.ListWarmPools(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"pagination": {
"pageSize": 1
}
}
```
## Request
`gitpod.v1.ListWarmPoolsRequest`
| Field | Type | Required | Description |
| ------------ | -------------------------------------------------------- | -------- | ----------------------------------------------------------------- |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request) | No | pagination contains the pagination options for listing warm pools |
| `filter` | [Filter](#type-gitpod-v1-list-warm-pools-request-filter) | No | filter contains the filter options for listing warm pools |
## Response
`gitpod.v1.ListWarmPoolsResponse`
| Field | Type | Required | Description |
| ------------ | --------------------------------------------------------- | -------- | ----------------------------------------------------- |
| `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | pagination contains the pagination response |
| `warmPools` | array of [WarmPool](#type-gitpod-v1-warm-pool) | No | warm\_pools are the warm pools that matched the query |
## Related types
`gitpod.v1.ListWarmPoolsRequest.Filter`
| Field | Type | Required | Description |
| --------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectIds` | array of string | No | project\_ids filters warm pools to specific projects Constraints: `repeated.items.string.uuid=true, repeated.max_items=25`. |
| `environmentClassIds` | array of string | No | environment\_class\_ids filters warm pools to specific environment classes Constraints: `repeated.items.string.uuid=true, repeated.max_items=25`. |
`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 |
WarmPool maintains pre-created environment instances from a prebuild snapshot
for near-instant environment startup.
One warm pool exists per \ pair.
`gitpod.v1.WarmPool`
| Field | Type | Required | Description |
| ---------- | ------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------- |
| `id` | string | No | id is the unique identifier for the warm pool Constraints: `string.uuid=true`. |
| `metadata` | [WarmPoolMetadata](#type-gitpod-v1-warm-pool-metadata) | Yes | metadata contains organizational and ownership information Constraints: `required=true`. |
| `spec` | [WarmPoolSpec](#type-gitpod-v1-warm-pool-spec) | Yes | spec contains the desired configuration for this warm pool Constraints: `required=true`. |
| `status` | [WarmPoolStatus](#type-gitpod-v1-warm-pool-status) | Yes | status contains the current status reported by the runner Constraints: `required=true`. |
WarmPoolMetadata contains metadata about the warm pool
`gitpod.v1.WarmPoolMetadata`
| Field | Type | Required | Description |
| -------------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `organizationId` | string | No | organization\_id is the ID of the organization that owns the warm pool Constraints: `string.uuid=true`. |
| `projectId` | string | No | project\_id is the ID of the project this warm pool belongs to Constraints: `string.uuid=true`. |
| `environmentClassId` | string | No | environment\_class\_id is the environment class whose instances are warmed Constraints: `string.uuid=true`. |
| `runnerId` | string | No | runner\_id is the runner that manages this warm pool. Derived from the environment class. Constraints: `string.uuid=true`. |
| `createdAt` | RFC 3339 timestamp | Yes | created\_at is when the warm pool was created Constraints: `required=true`. |
| `updatedAt` | RFC 3339 timestamp | Yes | updated\_at is when the warm pool was last updated Constraints: `required=true`. |
WarmPoolSpec contains the desired configuration for a warm pool
`gitpod.v1.WarmPoolSpec`
| Field | Type | Required | Description |
| -------------- | ------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `specVersion` | 64-bit integer string | No | spec\_version is incremented each time the spec is updated. Used for optimistic concurrency control. |
| `desiredSize` | integer | No | **Deprecated.** desired\_size is the number of warm instances to maintain. Deprecated: Use min\_size and max\_size instead for dynamic scaling. Existing pools will be migrated to min\_size=max\_size=desired\_size. Constraints: `ignore=1, int32.gte=1, int32.lte=20`. |
| `snapshotId` | string | No | snapshot\_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. Constraints: `ignore=1, string.uuid=true`. |
| `desiredPhase` | [WarmPoolPhase](#enum-gitpod-v1-warm-pool-phase) | No | desired\_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. Constraints: `enum.defined_only=true`. |
| `minSize` | integer | No | min\_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and \<= max\_size. Set to 0 to allow full scale-down. Constraints: `int32.gte=0, int32.lte=20`. |
| `maxSize` | integer | No | max\_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min\_size and \<= 20. Constraints: `int32.gte=1, int32.lte=20`. |
WarmPoolStatus contains the current status of a warm pool as reported by the runner
`gitpod.v1.WarmPoolStatus`
| Field | Type | Required | Description |
| ------------------ | ------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phase` | [WarmPoolPhase](#enum-gitpod-v1-warm-pool-phase) | Yes | phase is the current phase of the warm pool lifecycle Constraints: `enum.defined_only=true, required=true`. |
| `failureMessage` | string | No | failure\_message contains details about why the warm pool is degraded or failed |
| `statusVersion` | 64-bit integer string | No | status\_version is incremented each time the status is updated. Used for optimistic concurrency control. |
| `runningInstances` | integer | No | running\_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. |
| `stoppedInstances` | integer | No | stopped\_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. |
| `desiredSize` | integer | No | desired\_size is the current target number of instances the autoscaler has decided on. Unlike running\_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. |
WarmPoolPhase represents the lifecycle phase of a warm pool
| Value | Number | Description |
| ----------------------------- | -----: | --------------------------------------------------------------------------------------------------- |
| `WARM_POOL_PHASE_UNSPECIFIED` | 0 | WARM\_POOL\_PHASE\_UNSPECIFIED is the default value and should not be used |
| `WARM_POOL_PHASE_PENDING` | 10 | WARM\_POOL\_PHASE\_PENDING indicates the warm pool has been created but no snapshot is assigned yet |
| `WARM_POOL_PHASE_READY` | 20 | WARM\_POOL\_PHASE\_READY indicates the runner has acknowledged the pool and instances are available |
| `WARM_POOL_PHASE_DEGRADED` | 30 | WARM\_POOL\_PHASE\_DEGRADED indicates the runner reported a problem with the pool |
| `WARM_POOL_PHASE_DELETING` | 40 | WARM\_POOL\_PHASE\_DELETING indicates the warm pool is being deleted and instances are draining |
| `WARM_POOL_PHASE_DELETED` | 50 | WARM\_POOL\_PHASE\_DELETED indicates the warm pool has been fully cleaned up |