---
title: "ListServices"
method: POST
path: "/gitpod.v1.EnvironmentAutomationService/ListServices"
tags: ["gitpod.v1.EnvironmentAutomationService"]
---

# ListServices

`POST /gitpod.v1.EnvironmentAutomationService/ListServices`

Lists automation services with optional filtering.

 Use this method to:
 - View all services in an environment
 - Filter services by reference
 - Monitor service status

 ### Examples

 - List environment services:

   Shows all services for an environment.

   ```yaml
   filter:
     environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"]
   pagination:
     pageSize: 20
   ```

 - Filter by reference:

   Lists services matching specific references.

   ```yaml
   filter:
     references: ["web-server", "database"]
   pagination:
     pageSize: 20
   ```

## Query parameters

- `pageSize` integer
- `token` string

## Request body

- GitpodV1ListServicesRequest
  - `filter` GitpodV1ListServicesRequestFilter
    - `environmentIds` string[] — environment_ids filters the response to only services of these environments
    - `references` string[] — references filters the response to only services with these references
    - `roles` GitpodV1ServiceRole[] — roles filters the response to only services with these roles
    - `serviceIds` string[] — service_ids filters the response to only services with these IDs
  - `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

- GitpodV1ListServicesResponse
  - `pagination` GitpodV1PaginationResponse
    - `nextToken` string — Token passed for retrieving the next set of results. Empty if there are no more results
  - `services` GitpodV1Service[]
    - `environmentId` string, uuid
    - `id` string, uuid, required
    - `metadata` GitpodV1ServiceMetadata — unresolved $ref
    - `spec` GitpodV1ServiceSpec — unresolved $ref
    - `status` GitpodV1ServiceStatus
      - `failureMessage` string — 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 — log_url contains the URL at which the service logs can be accessed.
      - `output` object — output contains the output of the service. setting an output field to empty string will unset it.
      - `phase` 'SERVICE_PHASE_UNSPECIFIED' | 'SERVICE_PHASE_STARTING' | 'SERVICE_PHASE_RUNNING' | 'SERVICE_PHASE_STOPPING' | 'SERVICE_PHASE_STOPPED' | 'SERVICE_PHASE_FAILED' | 'SERVICE_PHASE_DELETED'
      - `session` string — session is the current session of the service.
      - `statusVersion` string — 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.

## Other responses

- `default` — Error

## Changes

- **2026-07-30** `44d50c2ac284` — 1 breaking, 1 warning, 2 info
  - added `subschema #1, subschema #2` to the `services/items/spec/runsOn` response property `oneOf` list for the response status `200`
  - removed the optional property `services/items/spec/runsOn/terminal` from the response with the `200` status
  - added the optional property `services/items/spec/readinessTimeout` to the response with the `200` status
  - removed `subschema #1, subschema #2, subschema #3` from the `services/items/spec/runsOn` response property `oneOf` list for the response status `200`
- **2026-04-02** `dabc0ff98cd7` — 1 breaking, 3 info
  - added `subschema #1, subschema #2, subschema #3` to the `services/items/spec/runsOn` response property `oneOf` list for the response status `200`
  - added the optional property `services/items/spec/runsOn/terminal` to the response with the `200` status
  - removed the `PRINCIPAL_AGENT_EXECUTION` enum value from the `services/items/metadata/creator/principal` response property for the response status `200`
  - removed `subschema #1, subschema #2` from the `services/items/spec/runsOn` response property `oneOf` list for the response status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.EnvironmentAutomationService/ListServices/post.md)

---

[API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/44d50c2ac284/schema)