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

  ```yaml
  pagination:
    pageSize: 20
  ```

- Filter by provider:

  Lists only AWS EC2 runners.

  ```yaml
  filter:
    providers: ["RUNNER_PROVIDER_AWS_EC2"]
  pagination:
    pageSize: 20
  ```

### Parameters

- `token: Optional[str]`

- `page_size: Optional[int]`

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

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

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

- `pagination: Optional[Pagination]`

  pagination contains the pagination options for listing runners

  - `token: Optional[str]`

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

  - `page_size: Optional[int]`

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

### Returns

- `class Runner: …`

  - `created_at: Optional[datetime]`

    Time when the Runner was created.

  - `creator: Optional[Subject]`

    creator is the identity of the creator of the environment

    - `id: Optional[str]`

      id is the UUID of the subject

    - `principal: Optional[Principal]`

      Principal is the principal of the subject

      - `"PRINCIPAL_UNSPECIFIED"`

      - `"PRINCIPAL_ACCOUNT"`

      - `"PRINCIPAL_USER"`

      - `"PRINCIPAL_RUNNER"`

      - `"PRINCIPAL_ENVIRONMENT"`

      - `"PRINCIPAL_SERVICE_ACCOUNT"`

      - `"PRINCIPAL_RUNNER_MANAGER"`

  - `kind: Optional[RunnerKind]`

    The runner's kind

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

    - `"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.

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

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

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

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

      - `"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.

      - `"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.

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

    - `public_key: Optional[str]`

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

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

    - `version: Optional[str]`

  - `updated_at: Optional[datetime]`

    Time when the Runner was last udpated.

### Example

```python
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)
```

#### Response

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