## ListWarmPools

**post** `/gitpod.v1.PrebuildService/ListWarmPools`

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
  filter:
    projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"]
  ```

### Query Parameters

- `token: optional string`

- `pageSize: optional number`

### Body Parameters

- `filter: optional object { environmentClassIds, projectIds }`

  filter contains the filter options for listing warm pools

  - `environmentClassIds: optional array of string`

    environment_class_ids filters warm pools to specific environment classes

  - `projectIds: optional array of string`

    project_ids filters warm pools to specific projects

- `pagination: optional object { token, pageSize }`

  pagination contains the pagination options for listing warm pools

  - `token: optional string`

    Token for the next set of results that was returned as next_token of a
    PaginationResponse

  - `pageSize: optional number`

    Page size is the maximum number of results to retrieve per page.
    Defaults to 25. Maximum 100.

### Returns

- `pagination: optional object { nextToken }`

  pagination contains the pagination response

  - `nextToken: optional string`

    Token passed for retrieving the next set of results. Empty if there are no
    more results

- `warmPools: optional array of WarmPool`

  warm_pools are the warm pools that matched the query

  - `metadata: WarmPoolMetadata`

    metadata contains organizational and ownership information

    - `createdAt: string`

      created_at is when the warm pool was created

    - `updatedAt: string`

      updated_at is when the warm pool was last updated

    - `environmentClassId: optional string`

      environment_class_id is the environment class whose instances are warmed

    - `organizationId: optional string`

      organization_id is the ID of the organization that owns the warm pool

    - `projectId: optional string`

      project_id is the ID of the project this warm pool belongs to

    - `runnerId: optional string`

      runner_id is the runner that manages this warm pool.
      Derived from the environment class.

  - `spec: WarmPoolSpec`

    spec contains the desired configuration for this warm pool

    - `desiredPhase: optional WarmPoolPhase`

      desired_phase is the intended lifecycle phase for this warm pool.
      Managed by the API and reconciler.

      - `"WARM_POOL_PHASE_UNSPECIFIED"`

      - `"WARM_POOL_PHASE_PENDING"`

      - `"WARM_POOL_PHASE_READY"`

      - `"WARM_POOL_PHASE_DEGRADED"`

      - `"WARM_POOL_PHASE_DELETING"`

      - `"WARM_POOL_PHASE_DELETED"`

    - `desiredSize: optional number`

      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.

    - `maxSize: optional number`

      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.

    - `minSize: optional number`

      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.

    - `snapshotId: optional string`

      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.

    - `specVersion: optional string`

      spec_version is incremented each time the spec is updated.
      Used for optimistic concurrency control.

  - `status: WarmPoolStatus`

    status contains the current status reported by the runner

    - `phase: WarmPoolPhase`

      phase is the current phase of the warm pool lifecycle

    - `desiredSize: optional number`

      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.

    - `failureMessage: optional string`

      failure_message contains details about why the warm pool is degraded or failed

    - `runningInstances: optional number`

      running_instances is the number of running warm instances in the pool,
      ready to be claimed for near-instant environment startup.

    - `statusVersion: optional string`

      status_version is incremented each time the status is updated.
      Used for optimistic concurrency control.

    - `stoppedInstances: optional number`

      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.

  - `id: optional string`

    id is the unique identifier for the warm pool

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/ListWarmPools \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "pagination": {
    "nextToken": "nextToken"
  },
  "warmPools": [
    {
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "runnerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "spec": {
        "desiredPhase": "WARM_POOL_PHASE_UNSPECIFIED",
        "desiredSize": 1,
        "maxSize": 1,
        "minSize": 20,
        "snapshotId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "specVersion": "specVersion"
      },
      "status": {
        "phase": "WARM_POOL_PHASE_UNSPECIFIED",
        "desiredSize": 0,
        "failureMessage": "failureMessage",
        "runningInstances": 0,
        "statusVersion": "statusVersion",
        "stoppedInstances": 0
      },
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
    }
  ]
}
```