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

# Get Service

> Gets details about a specific automation service.

`Unary` · [`Environment Automations`](/docs/api-reference/generated/environment-automation/overview)

Gets details about a specific automation service.

Use this method to:

* Check service status
* View service configuration
* Monitor service health
* Retrieve service metadata

### Examples

* Get service details:

  Retrieves information about a specific service.

  ```yaml theme={null}
  id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  ```

## Endpoint

```text theme={null}
POST /api/gitpod.v1.EnvironmentAutomationService/GetService
```

Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.

## Request example

<CodeGroup>
  ```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.EnvironmentAutomationService/GetService" \
    --header "Authorization: Bearer $ONA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
    "id": "<id>"
  }'
  ```

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

  ona = create_client_from_env()
  request = environment_automation_pb2.GetServiceRequest(
      id="<id>",
  )
  response = ona.services.environment_automation.get_service(request)
  print(response)
  ```

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

  async function main() {
    const ona = createClientFromEnv();
    const request = create(GetServiceRequestSchema, {
      id: "<id>",
    });
    const response = await ona.services.environmentAutomation.getService(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.GetServiceRequest{
  		Id: "<id>",
  	})
  	response, err := ona.Services.EnvironmentAutomation.GetService(context.Background(), request)
  	if err != nil {
  		log.Fatal(err)
  	}
  	fmt.Println(response.Msg)
  }
  ```

  ```json Request body theme={null}
  {
    "id": "<id>"
  }
  ```
</CodeGroup>

## Request

`gitpod.v1.GetServiceRequest`

| Field | Type   | Required | Description                      |
| ----- | ------ | -------- | -------------------------------- |
| `id`  | string | No       | Constraints: `string.uuid=true`. |

## Response

`gitpod.v1.GetServiceResponse`

| Field     | Type                               | Required | Description                   |
| --------- | ---------------------------------- | -------- | ----------------------------- |
| `service` | [Service](#type-gitpod-v1-service) | Yes      | Constraints: `required=true`. |

## Related types

<a id="type-gitpod-v1-service" />

<Accordion title="Service">
  `gitpod.v1.Service`

  | Field           | Type                                                | Required | Description                      |
  | --------------- | --------------------------------------------------- | -------- | -------------------------------- |
  | `id`            | string                                              | No       | Constraints: `string.uuid=true`. |
  | `environmentId` | string                                              | No       | Constraints: `string.uuid=true`. |
  | `metadata`      | [ServiceMetadata](#type-gitpod-v1-service-metadata) | No       |                                  |
  | `spec`          | [ServiceSpec](#type-gitpod-v1-service-spec)         | No       |                                  |
  | `status`        | [ServiceStatus](#type-gitpod-v1-service-status)     | No       |                                  |
</Accordion>

<a id="type-gitpod-v1-service-metadata" />

<Accordion title="ServiceMetadata">
  `gitpod.v1.ServiceMetadata`

  | Field         | Type                                        | Required | Description                                                                                                                                                                                                                                                                          |
  | ------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `reference`   | string                                      | No       | reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). Constraints: `string.pattern=^[a-zA-Z0-9_-]&#123;1,128&#125;$`. |
  | `name`        | string                                      | No       | name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. Constraints: `string.min_len=1`.                                                                     |
  | `description` | string                                      | No       | description is a user-facing description for the service. It can be used to provide context and documentation for the service.                                                                                                                                                       |
  | `createdAt`   | RFC 3339 timestamp                          | No       | created\_at is the time the service was created.                                                                                                                                                                                                                                     |
  | `creator`     | Subject                                     | No       | creator describes the principal who created the service.                                                                                                                                                                                                                             |
  | `triggeredBy` | array of AutomationTrigger                  | No       | triggered\_by is a list of trigger that start the service.                                                                                                                                                                                                                           |
  | `role`        | [ServiceRole](#enum-gitpod-v1-service-role) | No       | role specifies the intended role or purpose of the service.                                                                                                                                                                                                                          |
</Accordion>

<a id="type-gitpod-v1-service-spec" />

<Accordion title="ServiceSpec">
  `gitpod.v1.ServiceSpec`

  | Field              | Type                                          | Required | Description                                                                                                                                                                                                                         |
  | ------------------ | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `specVersion`      | 64-bit integer string                         | No       | version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec\_version \< b.spec\_version then a was the spec before b. |
  | `desiredPhase`     | [ServicePhase](#enum-gitpod-v1-service-phase) | No       | desired\_phase is the phase the service should be in. Used to start or stop the service. Constraints: `enum.defined_only=true`.                                                                                                     |
  | `commands`         | Commands                                      | No       | commands contains the commands to start, stop and check the readiness of the service                                                                                                                                                |
  | `session`          | string                                        | No       | session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed.                                                                                            |
  | `runsOn`           | RunsOn                                        | No       | runs\_on specifies the environment the service should run on.                                                                                                                                                                       |
  | `env`              | array of EnvironmentVariableItem              | No       | env specifies environment variables for the service.                                                                                                                                                                                |
  | `readinessTimeout` | duration string                               | No       | readiness\_timeout is the maximum duration a service may remain in the Starting phase while readiness checks run. 0s disables the timeout. Constraints: `duration.lte.seconds=86400`.                                               |
</Accordion>

<a id="type-gitpod-v1-service-status" />

<Accordion title="ServiceStatus">
  `gitpod.v1.ServiceStatus`

  | Field            | Type                                          | Required | Description                                                                                                                                                                                                                                                                                                                               |
  | ---------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `statusVersion`  | 64-bit integer string                         | No       | version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status\_version \< b.status\_version then a was the status before b. |
  | `phase`          | [ServicePhase](#enum-gitpod-v1-service-phase) | No       | phase is the current phase of the service.                                                                                                                                                                                                                                                                                                |
  | `failureMessage` | string                                        | No       | failure\_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state.                                                                                                                                                                       |
  | `logUrl`         | string                                        | No       | log\_url contains the URL at which the service logs can be accessed.                                                                                                                                                                                                                                                                      |
  | `session`        | string                                        | No       | session is the current session of the service.                                                                                                                                                                                                                                                                                            |
  | `output`         | map of string to string                       | No       | output contains the output of the service. setting an output field to empty string will unset it. Constraints: `map.keys.string.max_len=128, map.keys.string.min_len=1, map.values.string.max_len=4096, map.values.string.min_len=0`.                                                                                                     |
</Accordion>

<a id="enum-gitpod-v1-service-phase" />

<Accordion title="ServicePhase">
  | Value                       | Number | Description |
  | --------------------------- | -----: | ----------- |
  | `SERVICE_PHASE_UNSPECIFIED` |      0 |             |
  | `SERVICE_PHASE_STARTING`    |      1 |             |
  | `SERVICE_PHASE_RUNNING`     |      2 |             |
  | `SERVICE_PHASE_STOPPING`    |      3 |             |
  | `SERVICE_PHASE_STOPPED`     |      4 |             |
  | `SERVICE_PHASE_FAILED`      |      5 |             |
  | `SERVICE_PHASE_DELETED`     |      6 |             |
</Accordion>

<a id="enum-gitpod-v1-service-role" />

<Accordion title="ServiceRole">
  | Value                         | Number | Description |
  | ----------------------------- | -----: | ----------- |
  | `SERVICE_ROLE_UNSPECIFIED`    |      0 |             |
  | `SERVICE_ROLE_DEFAULT`        |      1 |             |
  | `SERVICE_ROLE_EDITOR`         |      2 |             |
  | `SERVICE_ROLE_AI_AGENT`       |      3 |             |
  | `SERVICE_ROLE_SECURITY_AGENT` |      4 |             |
</Accordion>