> ## 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 Task Execution

> Gets details about a specific task execution.

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

Gets details about a specific task execution.

Use this method to:

* Monitor execution progress
* View execution logs
* Check execution status
* Debug failed executions

### Examples

* Get execution details:

  Retrieves information about a specific task execution.

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

## Endpoint

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

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/GetTaskExecution" \
    --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.GetTaskExecutionRequest(
      id="<id>",
  )
  response = ona.services.environment_automation.get_task_execution(request)
  print(response)
  ```

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

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

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

## Request

`gitpod.v1.GetTaskExecutionRequest`

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

## Response

`gitpod.v1.GetTaskExecutionResponse`

| Field           | Type                                            | Required | Description                   |
| --------------- | ----------------------------------------------- | -------- | ----------------------------- |
| `taskExecution` | [TaskExecution](#type-gitpod-v1-task-execution) | Yes      | Constraints: `required=true`. |

## Related types

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