## ListWarmPools

`client.Prebuilds.ListWarmPools(ctx, params) (*WarmPoolsPage[WarmPool], error)`

**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"]
  ```

### Parameters

- `params PrebuildListWarmPoolsParams`

  - `Token param.Field[string]`

    Query param

  - `PageSize param.Field[int64]`

    Query param

  - `Filter param.Field[PrebuildListWarmPoolsParamsFilter]`

    Body param: filter contains the filter options for listing warm pools

    - `EnvironmentClassIDs []string`

      environment_class_ids filters warm pools to specific environment classes

    - `ProjectIDs []string`

      project_ids filters warm pools to specific projects

  - `Pagination param.Field[PrebuildListWarmPoolsParamsPagination]`

    Body param: pagination contains the pagination options for listing warm pools

    - `Token string`

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

    - `PageSize int64`

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

### Returns

- `type WarmPool struct{…}`

  WarmPool maintains pre-created environment instances from a prebuild snapshot
  for near-instant environment startup.
  One warm pool exists per <project, environment_class> pair.

  - `Metadata WarmPoolMetadata`

    metadata contains organizational and ownership information

    - `CreatedAt Time`

      created_at is when the warm pool was created

    - `UpdatedAt Time`

      updated_at is when the warm pool was last updated

    - `EnvironmentClassID string`

      environment_class_id is the environment class whose instances are warmed

    - `OrganizationID string`

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

    - `ProjectID string`

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

    - `RunnerID 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 WarmPoolPhase`

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

      - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"`

      - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"`

      - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"`

      - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"`

      - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"`

      - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"`

    - `DesiredSize int64`

      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 int64`

      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 int64`

      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 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 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 int64`

      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 string`

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

    - `RunningInstances int64`

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

    - `StatusVersion string`

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

    - `StoppedInstances int64`

      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 string`

    id is the unique identifier for the warm pool

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  page, err := client.Prebuilds.ListWarmPools(context.TODO(), gitpod.PrebuildListWarmPoolsParams{
    Filter: gitpod.F(gitpod.PrebuildListWarmPoolsParamsFilter{
      ProjectIDs: gitpod.F([]string{"b0e12f6c-4c67-429d-a4a6-d9838b5da047"}),
    }),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### 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"
    }
  ]
}
```