Skip to content
Ona API Reference
Ona Docs
API Reference
Runners

ListRunners

runners.list(RunnerListParams**kwargs) -> SyncRunnersPage[Runner]
POST/gitpod.v1.RunnerService/ListRunners

Lists all registered runners with optional filtering.

Use this method to:

  • View all available runners
  • Filter by runner type
  • Monitor runner status
  • Check runner availability

Examples

  • List all runners:

    Shows all runners with pagination.

    pagination:
  pageSize: 20

  • Filter by provider:

    Lists only AWS EC2 runners.

    filter:
  providers: ["RUNNER_PROVIDER_AWS_EC2"]
pagination:
  pageSize: 20
ParametersExpand Collapse
token: Optional[str]
page_size: Optional[int]
maximum100
minimum0
filter: Optional[Filter]
creator_ids: Optional[Sequence[str]]

creator_ids filters the response to only runner created by specified users

kinds: Optional[List[RunnerKind]]

kinds filters the response to only runners of the specified kinds

One of the following:
"RUNNER_KIND_UNSPECIFIED"
"RUNNER_KIND_LOCAL"
"RUNNER_KIND_REMOTE"
"RUNNER_KIND_LOCAL_CONFIGURATION"
providers: Optional[List[RunnerProvider]]

providers filters the response to only runners of the specified providers

One of the following:
"RUNNER_PROVIDER_UNSPECIFIED"
"RUNNER_PROVIDER_AWS_EC2"
"RUNNER_PROVIDER_LINUX_HOST"
"RUNNER_PROVIDER_DESKTOP_MAC"
"RUNNER_PROVIDER_MANAGED"
"RUNNER_PROVIDER_GCP"
"RUNNER_PROVIDER_DEV_AGENT"
ReturnsExpand Collapse
class Runner: …
created_at: Optional[datetime]

Time when the Runner was created.

formatdate-time
creator: Optional[Subject]

creator is the identity of the creator of the environment

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[Principal]

Principal is the principal of the subject

One of the following:
"PRINCIPAL_UNSPECIFIED"
"PRINCIPAL_ACCOUNT"
"PRINCIPAL_USER"
"PRINCIPAL_RUNNER"
"PRINCIPAL_ENVIRONMENT"
"PRINCIPAL_SERVICE_ACCOUNT"
"PRINCIPAL_RUNNER_MANAGER"
kind: Optional[RunnerKind]

The runner’s kind

One of the following:
"RUNNER_KIND_UNSPECIFIED"
"RUNNER_KIND_LOCAL"
"RUNNER_KIND_REMOTE"
"RUNNER_KIND_LOCAL_CONFIGURATION"
name: Optional[str]

The runner’s name which is shown to users

provider: Optional[RunnerProvider]

The runner’s provider

One of the following:
"RUNNER_PROVIDER_UNSPECIFIED"
"RUNNER_PROVIDER_AWS_EC2"
"RUNNER_PROVIDER_LINUX_HOST"
"RUNNER_PROVIDER_DESKTOP_MAC"
"RUNNER_PROVIDER_MANAGED"
"RUNNER_PROVIDER_GCP"
"RUNNER_PROVIDER_DEV_AGENT"
runner_id: Optional[str]
runner_manager_id: Optional[str]

The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners.

formatuuid
spec: Optional[RunnerSpec]

The runner’s specification

configuration: Optional[RunnerConfiguration]

The runner’s configuration

auto_update: Optional[bool]

auto_update indicates whether the runner should automatically update itself.

devcontainer_image_cache_enabled: Optional[bool]

devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners.

log_level: Optional[LogLevel]

log_level is the log level for the runner

One of the following:
"LOG_LEVEL_UNSPECIFIED"
"LOG_LEVEL_DEBUG"
"LOG_LEVEL_INFO"
"LOG_LEVEL_WARN"
"LOG_LEVEL_ERROR"
metrics: Optional[MetricsConfiguration]

metrics contains configuration for the runner’s metrics collection

enabled: Optional[bool]

enabled indicates whether the runner should collect metrics

managed_metrics_enabled: Optional[bool]

When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint.

password: Optional[str]

password is the password to use for the metrics collector

url: Optional[str]

url is the URL of the metrics collector

username: Optional[str]

username is the username to use for the metrics collector

region: Optional[str]

Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner’s status for the actual region.

release_channel: Optional[RunnerReleaseChannel]

The release channel the runner is on

One of the following:
"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"
"RUNNER_RELEASE_CHANNEL_STABLE"
"RUNNER_RELEASE_CHANNEL_LATEST"
update_window: Optional[UpdateWindow]

update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time.

end_hour: Optional[int]

end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2.

start_hour: Optional[int]

start_hour is the beginning of the update window as a UTC hour (0-23). +required

desired_phase: Optional[RunnerPhase]

RunnerPhase represents the phase a runner is in

One of the following:
"RUNNER_PHASE_UNSPECIFIED"
"RUNNER_PHASE_CREATED"
"RUNNER_PHASE_INACTIVE"
"RUNNER_PHASE_ACTIVE"
"RUNNER_PHASE_DELETING"
"RUNNER_PHASE_DELETED"
"RUNNER_PHASE_DEGRADED"
variant: Optional[RunnerVariant]

The runner’s variant

One of the following:
"RUNNER_VARIANT_UNSPECIFIED"
"RUNNER_VARIANT_STANDARD"
"RUNNER_VARIANT_ENTERPRISE"
status: Optional[RunnerStatus]

The runner’s status

additional_info: Optional[List[FieldValue]]

additional_info contains additional information about the runner, e.g. a CloudFormation stack URL.

key: Optional[str]
value: Optional[str]
capabilities: Optional[List[RunnerCapability]]

capabilities is a list of capabilities the runner supports.

One of the following:
"RUNNER_CAPABILITY_UNSPECIFIED"
"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"
"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"
"RUNNER_CAPABILITY_AGENT_EXECUTION"
"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"
"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"
"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"
"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"
"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"
"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"
"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"
"RUNNER_CAPABILITY_WARM_POOL"
"RUNNER_CAPABILITY_ASG_WARM_POOL"
"RUNNER_CAPABILITY_PORT_AUTHENTICATION"
gateway_info: Optional[GatewayInfo]

gateway_info is information about the gateway to which the runner is connected.

gateway: Optional[Gateway]

Gateway represents a system gateway that provides access to services

name: str

name is the human-readable name of the gateway. name is unique across all gateways.

url: str

url of the gateway

region: Optional[str]

region is the geographical region where the gateway is located

latency: Optional[str]

latency is the round-trip time of the runner to the gateway in milliseconds.

formatregex
llm_url: Optional[str]

llm_url is the URL of the LLM service to which the runner is connected.

log_url: Optional[str]
message: Optional[str]

The runner’s reported message which is shown to users. This message adds more context to the runner’s phase.

phase: Optional[RunnerPhase]

The runner’s reported phase

One of the following:
"RUNNER_PHASE_UNSPECIFIED"
"RUNNER_PHASE_CREATED"
"RUNNER_PHASE_INACTIVE"
"RUNNER_PHASE_ACTIVE"
"RUNNER_PHASE_DELETING"
"RUNNER_PHASE_DELETED"
"RUNNER_PHASE_DEGRADED"
public_key: Optional[str]

public_key is the runner’s public key used for encryption (32 bytes)

formatbyte
maxLength32
minLength32
region: Optional[str]

region is the region the runner is running in, if applicable.

support_bundle_url: Optional[str]

support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners.

system_details: Optional[str]
updated_at: Optional[datetime]

Time when the status was last updated.

formatdate-time
version: Optional[str]
updated_at: Optional[datetime]

Time when the Runner was last udpated.

formatdate-time

ListRunners

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
page = client.runners.list(
    filter={
        "providers": ["RUNNER_PROVIDER_AWS_EC2"]
    },
    pagination={
        "page_size": 20
    },
)
page = page.runners[0]
print(page.provider)
{
  "pagination": {
    "nextToken": "nextToken"
  },
  "runners": [
    {
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "kind": "RUNNER_KIND_UNSPECIFIED",
      "name": "name",
      "provider": "RUNNER_PROVIDER_UNSPECIFIED",
      "runnerId": "runnerId",
      "runnerManagerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "spec": {
        "configuration": {
          "autoUpdate": true,
          "continuousProfiling": true,
          "devcontainerImageCacheEnabled": true,
          "encryptedHoneycombApiKey": "U3RhaW5sZXNzIHJvY2tz",
          "logLevel": "LOG_LEVEL_UNSPECIFIED",
          "metrics": {
            "enabled": true,
            "includeVerboseMetrics": true,
            "managedMetricsEnabled": true,
            "password": "password",
            "url": "url",
            "username": "username"
          },
          "region": "region",
          "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED",
          "updateWindow": {
            "endHour": 0,
            "startHour": 0
          }
        },
        "desiredPhase": "RUNNER_PHASE_UNSPECIFIED",
        "variant": "RUNNER_VARIANT_UNSPECIFIED"
      },
      "status": {
        "additionalInfo": [
          {
            "key": "key",
            "value": "value"
          }
        ],
        "capabilities": [
          "RUNNER_CAPABILITY_UNSPECIFIED"
        ],
        "gatewayInfo": {
          "gateway": {
            "name": "name",
            "url": "url",
            "region": "region"
          },
          "latency": "+9125115.360s"
        },
        "llmUrl": "llmUrl",
        "logUrl": "logUrl",
        "message": "message",
        "phase": "RUNNER_PHASE_UNSPECIFIED",
        "publicKey": "U3RhaW5sZXNzIHJvY2tz",
        "region": "region",
        "supportBundleUrl": "supportBundleUrl",
        "systemDetails": "systemDetails",
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "version": "version"
      },
      "updatedAt": "2019-12-27T18:11:19.117Z"
    }
  ]
}
Returns Examples
{
  "pagination": {
    "nextToken": "nextToken"
  },
  "runners": [
    {
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "kind": "RUNNER_KIND_UNSPECIFIED",
      "name": "name",
      "provider": "RUNNER_PROVIDER_UNSPECIFIED",
      "runnerId": "runnerId",
      "runnerManagerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "spec": {
        "configuration": {
          "autoUpdate": true,
          "continuousProfiling": true,
          "devcontainerImageCacheEnabled": true,
          "encryptedHoneycombApiKey": "U3RhaW5sZXNzIHJvY2tz",
          "logLevel": "LOG_LEVEL_UNSPECIFIED",
          "metrics": {
            "enabled": true,
            "includeVerboseMetrics": true,
            "managedMetricsEnabled": true,
            "password": "password",
            "url": "url",
            "username": "username"
          },
          "region": "region",
          "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED",
          "updateWindow": {
            "endHour": 0,
            "startHour": 0
          }
        },
        "desiredPhase": "RUNNER_PHASE_UNSPECIFIED",
        "variant": "RUNNER_VARIANT_UNSPECIFIED"
      },
      "status": {
        "additionalInfo": [
          {
            "key": "key",
            "value": "value"
          }
        ],
        "capabilities": [
          "RUNNER_CAPABILITY_UNSPECIFIED"
        ],
        "gatewayInfo": {
          "gateway": {
            "name": "name",
            "url": "url",
            "region": "region"
          },
          "latency": "+9125115.360s"
        },
        "llmUrl": "llmUrl",
        "logUrl": "logUrl",
        "message": "message",
        "phase": "RUNNER_PHASE_UNSPECIFIED",
        "publicKey": "U3RhaW5sZXNzIHJvY2tz",
        "region": "region",
        "supportBundleUrl": "supportBundleUrl",
        "systemDetails": "systemDetails",
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "version": "version"
      },
      "updatedAt": "2019-12-27T18:11:19.117Z"
    }
  ]
}