--- title: "ListWarmPools" method: POST path: "/gitpod.v1.PrebuildService/ListWarmPools" tags: ["gitpod.v1.PrebuildService"] --- # 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 - `pageSize` integer - `token` string ## Request body - GitpodV1ListWarmPoolsRequest - `filter` GitpodV1ListWarmPoolsRequestFilter - `environmentClassIds` string[] — environment_class_ids filters warm pools to specific environment classes - `projectIds` string[] — project_ids filters warm pools to specific projects - `pagination` GitpodV1PaginationRequest - `pageSize` integer — Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. - `token` string — Token for the next set of results that was returned as next_token of a PaginationResponse ## Response `200` Success - GitpodV1ListWarmPoolsResponse - `pagination` GitpodV1PaginationResponse - `nextToken` string — Token passed for retrieving the next set of results. Empty if there are no more results - `warmPools` GitpodV1WarmPool[] — warm_pools are the warm pools that matched the query - `id` string, uuid — id is the unique identifier for the warm pool - `metadata` GitpodV1WarmPoolMetadata, required — WarmPoolMetadata contains metadata about the warm pool - `createdAt` string, date-time, required — A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format. - `environmentClassId` string, uuid — environment_class_id is the environment class whose instances are warmed - `organizationId` string, uuid — organization_id is the ID of the organization that owns the warm pool - `projectId` string, uuid — project_id is the ID of the project this warm pool belongs to - `runnerId` string, uuid — runner_id is the runner that manages this warm pool. Derived from the environment class. - `updatedAt` string, date-time, required — A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format. - `spec` GitpodV1WarmPoolSpec, required — WarmPoolSpec contains the desired configuration for a warm pool - `desiredPhase` 'WARM_POOL_PHASE_UNSPECIFIED' | 'WARM_POOL_PHASE_PENDING' | 'WARM_POOL_PHASE_READY' | 'WARM_POOL_PHASE_DEGRADED' | 'WARM_POOL_PHASE_DELETING' | 'WARM_POOL_PHASE_DELETED' — WarmPoolPhase represents the lifecycle phase of a warm pool - `desiredSize` integer — 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` integer, nullable — 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` integer, nullable — 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, uuid, nullable — 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` GitpodV1WarmPoolStatus, required — WarmPoolStatus contains the current status of a warm pool as reported by the runner - `desiredSize` integer — 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 - `phase` 'WARM_POOL_PHASE_UNSPECIFIED' | 'WARM_POOL_PHASE_PENDING' | 'WARM_POOL_PHASE_READY' | 'WARM_POOL_PHASE_DEGRADED' | 'WARM_POOL_PHASE_DELETING' | 'WARM_POOL_PHASE_DELETED', required — WarmPoolPhase represents the lifecycle phase of a warm pool - `runningInstances` integer — 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` integer — 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. ## Other responses - `default` — Error --- [API](https://skmtc.net/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.net/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/versions/44d50c2ac284/schema)