> ## 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.

# Update Warm Pool

> Updates a warm pool's configuration.

`Unary` · [`Prebuilds`](https://ona.com/docs/api-reference/generated/prebuild/overview)

Updates a warm pool's configuration.

Use this method to change the desired pool size.

### Examples

* Update pool size:

  ```yaml theme={null}
  warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab"
  desiredSize: 5
  ```

## Endpoint

```text theme={null}
POST /api/gitpod.v1.PrebuildService/UpdateWarmPool
```

Send a Bearer token as described in [Authentication](https://ona.com/docs/api-reference.md#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=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.PrebuildService/UpdateWarmPool" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "warmPoolId": "<warm-pool-id>"
}'
```

```python Python theme={null}
import gitpod.v1.prebuild_pb2 as prebuild_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
request = prebuild_pb2.UpdateWarmPoolRequest(
    warm_pool_id="<warm-pool-id>",
)
response = ona.services.prebuild.update_warm_pool(request)
print(response)
```

```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { UpdateWarmPoolRequestSchema } from "@gitpod/sdk/gitpod/v1/prebuild_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(UpdateWarmPoolRequestSchema, {
    warmPoolId: "<warm-pool-id>",
  });
  const response = await ona.services.prebuild.updateWarmPool(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.UpdateWarmPoolRequest{
		WarmPoolId: "<warm-pool-id>",
	})
	response, err := ona.Services.Prebuild.UpdateWarmPool(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}
```

```json Request body theme={null}
{
  "warmPoolId": "<warm-pool-id>"
}
```

## Request

`gitpod.v1.UpdateWarmPoolRequest`

| Field | Type | Required | Description |
| - | - | - | - |
| `warmPoolId` | string | Yes | warm\_pool\_id specifies the warm pool to update Constraints: `required=true, string.uuid=true`. |
| `desiredSize` | integer | No | **Deprecated.** desired\_size updates the number of warm instances to maintain. Deprecated: Use min\_size and max\_size instead for dynamic scaling. Constraints: `int32.gte=1, int32.lte=20`. |
| `minSize` | integer | No | min\_size updates 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 updates 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`. |

## Response

`gitpod.v1.UpdateWarmPoolResponse`

| Field | Type | Required | Description |
| - | - | - | - |
| `warmPool` | [WarmPool](#type-gitpod-v1-warm-pool) | Yes | Constraints: `required=true`. |

## Related types

> [accordion] WarmPool
>
> WarmPool maintains pre-created environment instances from a prebuild snapshot
> for near-instant environment startup.
> One warm pool exists per \<project, environment\_class> 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`. |

> [accordion] WarmPoolMetadata
>
> 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`. |

> [accordion] WarmPoolSpec
>
> 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`. |

> [accordion] WarmPoolStatus
>
> 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. |

> [accordion] WarmPoolPhase
>
> 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.