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

# List Task Executions

> Lists executions of automation tasks.

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

Lists executions of automation tasks.

Use this method to:

* View task execution history
* Monitor running tasks
* Track task completion status

### Examples

* List all executions:

  Shows execution history for all tasks.

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

* Filter by phase:

  Lists executions in specific phases.

  ```yaml theme={null}
  filter:
    phases: ["TASK_EXECUTION_PHASE_RUNNING", "TASK_EXECUTION_PHASE_FAILED"]
  pagination:
    pageSize: 20
  ```

## Endpoint

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

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/ListTaskExecutions" \
    --header "Authorization: Bearer $ONA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
    "pagination": {
      "pageSize": 1
    }
  }'
  ```

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

  ona = create_client_from_env()
  request = environment_automation_pb2.ListTaskExecutionsRequest(
      pagination=pagination_pb2.PaginationRequest(
          page_size=1,
      ),
  )
  response = ona.services.environment_automation.list_task_executions(request)
  print(response)
  ```

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

  async function main() {
    const ona = createClientFromEnv();
    const request = create(ListTaskExecutionsRequestSchema, {
      pagination: {
        pageSize: 1,
      },
    });
    const response = await ona.services.environmentAutomation.listTaskExecutions(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.ListTaskExecutionsRequest{
  		Pagination: &gitpodpb.PaginationRequest{
  			PageSize: 1,
  		},
  	})
  	response, err := ona.Services.EnvironmentAutomation.ListTaskExecutions(context.Background(), request)
  	if err != nil {
  		log.Fatal(err)
  	}
  	fmt.Println(response.Msg)
  }
  ```

  ```json Request body theme={null}
  {
    "pagination": {
      "pageSize": 1
    }
  }
  ```
</CodeGroup>

## Request

`gitpod.v1.ListTaskExecutionsRequest`

| Field        | Type                                                          | Required | Description                                                      |
| ------------ | ------------------------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request)       | No       | pagination contains the pagination options for listing task runs |
| `filter`     | [Filter](#type-gitpod-v1-list-task-executions-request-filter) | No       | filter contains the filter options for listing task runs         |

## Response

`gitpod.v1.ListTaskExecutionsResponse`

| Field            | Type                                                      | Required | Description |
| ---------------- | --------------------------------------------------------- | -------- | ----------- |
| `pagination`     | [PaginationResponse](#type-gitpod-v1-pagination-response) | No       |             |
| `taskExecutions` | array of [TaskExecution](#type-gitpod-v1-task-execution)  | No       |             |

## Related types

<a id="type-gitpod-v1-list-task-executions-request-filter" />

<Accordion title="Filter">
  `gitpod.v1.ListTaskExecutionsRequest.Filter`

  | Field            | Type                                                                | Required | Description                                                                                                                                                                |
  | ---------------- | ------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `taskIds`        | array of string                                                     | No       | task\_ids filters the response to only task runs of these tasks Constraints: `repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0`.               |
  | `taskReferences` | array of string                                                     | No       | task\_references filters the response to only task runs with this reference Constraints: `repeated.max_items=25, repeated.min_items=0`.                                    |
  | `environmentIds` | array of string                                                     | No       | environment\_ids filters the response to only task runs of these environments Constraints: `repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0`. |
  | `phases`         | array of [TaskExecutionPhase](#enum-gitpod-v1-task-execution-phase) | No       | phases filters the response to only task runs in these phases Constraints: `repeated.max_items=25, repeated.min_items=0`.                                                  |
</Accordion>

<a id="type-gitpod-v1-pagination-request" />

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

  | Field      | Type    | Required | Description                                                                                                                              |
  | ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
  | `pageSize` | integer | No       | Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. Constraints: `int32.gte=0, int32.lte=100`. |
  | `token`    | string  | No       | Token for the next set of results that was returned as next\_token of a PaginationResponse                                               |
</Accordion>

<a id="type-gitpod-v1-pagination-response" />

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

  | Field       | Type   | Required | Description                                                                             |
  | ----------- | ------ | -------- | --------------------------------------------------------------------------------------- |
  | `nextToken` | string | No       | Token passed for retrieving the next set of results. Empty if there are no more results |
</Accordion>

<a id="type-gitpod-v1-task-execution" />

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

  | Field      | Type                                                             | Required | Description                      |
  | ---------- | ---------------------------------------------------------------- | -------- | -------------------------------- |
  | `id`       | string                                                           | No       | Constraints: `string.uuid=true`. |
  | `metadata` | [TaskExecutionMetadata](#type-gitpod-v1-task-execution-metadata) | No       |                                  |
  | `spec`     | [TaskExecutionSpec](#type-gitpod-v1-task-execution-spec)         | No       |                                  |
  | `status`   | [TaskExecutionStatus](#type-gitpod-v1-task-execution-status)     | No       |                                  |
</Accordion>

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

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

  | Field           | Type               | Required | Description                                                                                                      |
  | --------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
  | `taskId`        | string             | No       | task\_id is the ID of the main task being executed. Constraints: `string.uuid=true`.                             |
  | `environmentId` | string             | No       | environment\_id is the ID of the environment in which the task run is executed. Constraints: `string.uuid=true`. |
  | `createdAt`     | RFC 3339 timestamp | No       | created\_at is the time the task was created.                                                                    |
  | `creator`       | Subject            | No       | creator describes the principal who created/started the task run.                                                |
  | `startedBy`     | string             | No       | started\_by describes the trigger that started the task execution.                                               |
  | `startedAt`     | RFC 3339 timestamp | No       | started\_at is the time the task execution actually started to run.                                              |
  | `completedAt`   | RFC 3339 timestamp | No       | completed\_at is the time the task execution was done.                                                           |
</Accordion>

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

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

  | Field          | Type                                                       | Required | Description                                                                                                                                                                                     |
  | -------------- | ---------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `plan`         | array of Group                                             | No       | plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. |
  | `desiredPhase` | [TaskExecutionPhase](#enum-gitpod-v1-task-execution-phase) | No       | desired\_phase is the phase the task execution should be in. Used to stop a running task execution early. Constraints: `enum.defined_only=true`.                                                |
</Accordion>

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

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

  | Field            | Type                                                       | Required | Description                                                                                                                                                                                                                                                                                                                             |
  | ---------------- | ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `statusVersion`  | 64-bit integer string                                      | No       | version of the status update. Task executions 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`          | [TaskExecutionPhase](#enum-gitpod-v1-task-execution-phase) | No       | the phase of a task execution represents the aggregated phase of all steps.                                                                                                                                                                                                                                                             |
  | `failureMessage` | string                                                     | No       | failure\_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state.                                                                                                                                                       |
  | `steps`          | array of Step                                              | No       | steps provides the status for each individual step of the task execution. If a step is missing it has not yet started.                                                                                                                                                                                                                  |
  | `logUrl`         | string                                                     | No       | log\_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started.                                                                                                                                                                                                              |
</Accordion>

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

<Accordion title="TaskExecutionPhase">
  | Value                              | Number | Description |
  | ---------------------------------- | -----: | ----------- |
  | `TASK_EXECUTION_PHASE_UNSPECIFIED` |      0 |             |
  | `TASK_EXECUTION_PHASE_PENDING`     |      1 |             |
  | `TASK_EXECUTION_PHASE_RUNNING`     |      2 |             |
  | `TASK_EXECUTION_PHASE_SUCCEEDED`   |      3 |             |
  | `TASK_EXECUTION_PHASE_FAILED`      |      4 |             |
  | `TASK_EXECUTION_PHASE_STOPPED`     |      5 |             |
</Accordion>