## GetRunner

`client.runners.retrieve(RunnerRetrieveParamsbody, RequestOptionsoptions?): RunnerRetrieveResponse`

**post** `/gitpod.v1.RunnerService/GetRunner`

Gets details about a specific runner.

Use this method to:

- Check runner status
- View runner configuration
- Monitor runner health
- Verify runner capabilities

### Examples

- Get runner details:

  Retrieves information about a specific runner.

  ```yaml
  runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  ```

### Parameters

- `body: RunnerRetrieveParams`

  - `runnerId?: string`

### Returns

- `RunnerRetrieveResponse`

  - `runner: Runner`

    - `createdAt?: string`

      Time when the Runner was created.

    - `creator?: Subject`

      creator is the identity of the creator of the environment

      - `id?: string`

        id is the UUID of the subject

      - `principal?: 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?: RunnerKind`

      The runner's kind

      - `"RUNNER_KIND_UNSPECIFIED"`

      - `"RUNNER_KIND_LOCAL"`

      - `"RUNNER_KIND_REMOTE"`

      - `"RUNNER_KIND_LOCAL_CONFIGURATION"`

    - `name?: string`

      The runner's name which is shown to users

    - `provider?: 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"`

    - `runnerId?: string`

    - `runnerManagerId?: string`

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

    - `spec?: RunnerSpec`

      The runner's specification

      - `configuration?: RunnerConfiguration`

        The runner's configuration

        - `autoUpdate?: boolean`

          auto_update indicates whether the runner should automatically update itself.

        - `devcontainerImageCacheEnabled?: boolean`

          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.

        - `logLevel?: 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?: MetricsConfiguration`

          metrics contains configuration for the runner's metrics collection

          - `enabled?: boolean`

            enabled indicates whether the runner should collect metrics

          - `managedMetricsEnabled?: boolean`

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

          - `password?: string`

            password is the password to use for the metrics collector

          - `url?: string`

            url is the URL of the metrics collector

          - `username?: string`

            username is the username to use for the metrics collector

        - `region?: string`

          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.

        - `releaseChannel?: RunnerReleaseChannel`

          The release channel the runner is on

          - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"`

          - `"RUNNER_RELEASE_CHANNEL_STABLE"`

          - `"RUNNER_RELEASE_CHANNEL_LATEST"`

        - `updateWindow?: UpdateWindow`

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

          - `endHour?: number | null`

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

          - `startHour?: number | null`

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

      - `desiredPhase?: 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?: RunnerVariant`

        The runner's variant

        - `"RUNNER_VARIANT_UNSPECIFIED"`

        - `"RUNNER_VARIANT_STANDARD"`

        - `"RUNNER_VARIANT_ENTERPRISE"`

    - `status?: RunnerStatus`

      The runner's status

      - `additionalInfo?: Array<FieldValue>`

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

        - `key?: string`

        - `value?: string`

      - `capabilities?: Array<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"`

      - `gatewayInfo?: GatewayInfo`

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

        - `gateway?: Gateway`

          Gateway represents a system gateway that provides access to services

          - `name: string`

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

          - `url: string`

            url of the gateway

          - `region?: string`

            region is the geographical region where the gateway is located

        - `latency?: string`

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

      - `llmUrl?: string`

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

      - `logUrl?: string`

      - `message?: string`

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

      - `phase?: RunnerPhase`

        The runner's reported phase

      - `publicKey?: string`

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

      - `region?: string`

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

      - `supportBundleUrl?: string`

        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.

      - `systemDetails?: string`

      - `updatedAt?: string`

        Time when the status was last updated.

      - `version?: string`

    - `updatedAt?: string`

      Time when the Runner was last udpated.

### Example

```typescript
import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

const runner = await client.runners.retrieve({ runnerId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68' });

console.log(runner.runner);
```

#### Response

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