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

> Gets details about a specific agent run, including its metadata, specification,

`Unary` · [`Agents`](https://ona.com/docs/api-reference/generated/agent/overview)

Gets details about a specific agent run, including its metadata, specification,
and status (phase, error messages, and usage statistics).

Use this method to:

* Monitor the run's progress
* Retrieve the agent's conversation URL
* Check if an agent run is actively producing output

### Examples

* Get agent run details by ID:

  ```yaml theme={null}
  agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"
  ```

## Endpoint

```text theme={null}
POST /api/gitpod.v1.AgentService/GetAgentExecution
```

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

## Request example

```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.AgentService/GetAgentExecution" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "agentExecutionId": "<agent-execution-id>"
}'
```

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

ona = create_client_from_env()
request = agent_pb2.GetAgentExecutionRequest(
    agent_execution_id="<agent-execution-id>",
)
response = ona.services.agent.get_agent_execution(request)
print(response)
```

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

async function main() {
  const ona = createClientFromEnv();
  const request = create(GetAgentExecutionRequestSchema, {
    agentExecutionId: "<agent-execution-id>",
  });
  const response = await ona.services.agent.getAgentExecution(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.GetAgentExecutionRequest{
		AgentExecutionId: "<agent-execution-id>",
	})
	response, err := ona.Services.Agent.GetAgentExecution(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}
```

```json Request body theme={null}
{
  "agentExecutionId": "<agent-execution-id>"
}
```

## Request

`gitpod.v1.GetAgentExecutionRequest`

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

## Response

`gitpod.v1.GetAgentExecutionResponse`

| Field | Type | Required | Description |
| - | - | - | - |
| `agentExecution` | [AgentExecution](#type-gitpod-v1-agent-execution) | No | |

## Related types

> [accordion] AgentExecution
>
> `gitpod.v1.AgentExecution`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | No | ID is a unique identifier of this agent run. No other agent run with the same name must be managed by this agent manager |
> | `metadata` | [Metadata](#type-gitpod-v1-agent-execution-metadata) | No | Metadata is data associated with this agent that's required for other parts of Gitpod to function |
> | `spec` | [Spec](#type-gitpod-v1-agent-execution-spec) | No | Spec is the configuration of the agent that's required for the runner to start the agent |
> | `status` | [Status](#type-gitpod-v1-agent-execution-status) | No | Status is the current status of the agent |

> [accordion] Metadata
>
> `gitpod.v1.AgentExecution.Metadata`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | No | |
> | `description` | string | No | |
> | `creator` | Subject | No | |
> | `createdAt` | RFC 3339 timestamp | No | |
> | `updatedAt` | RFC 3339 timestamp | No | |
> | `role` | [AgentExecutionRole](#enum-gitpod-v1-agent-execution-role) | No | role is the role of the agent execution |
> | `workflowActionId` | string | No | workflow\_action\_id is set when this agent execution was created as part of a workflow. Used to correlate agent executions with their parent workflow execution action. Constraints: `ignore=1, string.uuid=true`. |
> | `annotations` | map of string to string | No | annotations are key-value pairs for tracking external context. |
> | `sessionId` | string | No | session\_id is the ID of the session this agent execution belongs to. |

> [accordion] Spec
>
> `gitpod.v1.AgentExecution.Spec`
>
> | 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. |
> | `session` | string | No | |
> | `desiredPhase` | [Phase](#enum-gitpod-v1-agent-execution-phase) | No | desired\_phase is the desired phase of the agent run |
> | `agentId` | string | No | Constraints: `string.uuid=true`. |
> | `codeContext` | AgentCodeContext | No | |
> | `limits` | Limits | No | |
> | `codexSettings` | CodexSettings | No | codex\_settings contains persisted desired/manual settings for the Codex app agent. |

> [accordion] Status
>
> `gitpod.v1.AgentExecution.Status`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `statusVersion` | 64-bit integer string | No | version of the status. 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. |
> | `session` | string | No | |
> | `phase` | [Phase](#enum-gitpod-v1-agent-execution-phase) | No | |
> | `failureMessage` | string | No | failure\_message contains the reason the agent run failed to operate. |
> | `warningMessage` | string | No | warning\_message contains warnings, e.g. when the LLM is overloaded. |
> | `failureReason` | [AgentExecutionFailureReason](#enum-gitpod-v1-agent-execution-failure-reason) | No | failure\_reason contains a structured reason code for the failure. |
> | `conversationUrl` | string | No | conversation\_url is the URL to the conversation (all messages exchanged between the agent and the user) of the agent run. |
> | `transcriptUrl` | string | No | transcript\_url is the URL to the LLM transcript (all messages exchanged between the agent and the LLM) of the agent run. |
> | `supportBundleUrl` | string | No | support\_bundle\_url is the URL to download a diagnostic bundle for this agent execution. |
> | `conversationUrls` | ConversationURLs | No | conversation\_urls contains the v2 conversation streaming endpoints. When present, clients should use these URLs instead of conversation\_url. |
> | `iterations` | 64-bit integer string | No | |
> | `inputTokensUsed` | 64-bit integer string | No | |
> | `outputTokensUsed` | 64-bit integer string | No | |
> | `contextWindowLength` | 64-bit integer string | No | |
> | `cachedCreationTokensUsed` | 64-bit integer string | No | |
> | `cachedInputTokensUsed` | 64-bit integer string | No | |
> | `contextWindowLimit` | 64-bit integer string | No | context\_window\_limit is the selected model's maximum context window size in tokens. |
> | `judgement` | string | No | judgement is the judgement of the agent run produced by the judgement prompt. |
> | `currentOperation` | CurrentOperation | No | current\_operation is the current operation of the agent execution. |
> | `usedEnvironments` | array of EnvironmentUsage | No | used\_environments is the list of environments that were used by the agent execution. |
> | `currentActivity` | string | No | current\_activity is the current activity description of the agent execution. |
> | `outputs` | map of string to OutputValue | No | outputs is a map of key-value pairs that can be set by the agent during execution. Similar to task execution outputs, but with typed values for structured data. Constraints: `map.keys.string.max_len=128, map.keys.string.min_len=1`. |
> | `supportedModel` | [SupportedModel](#enum-gitpod-v1-supported-model) | No | supported\_model is the LLM model being used by the agent execution. |
> | `llmCapabilities` | LLMCapabilities | No | llm\_capabilities describes provider capabilities for the selected LLM integration. |
> | `mode` | [AgentMode](#enum-gitpod-v1-agent-mode) | No | mode is the current operational mode of the agent execution. This is set by the agent when entering different modes (e.g., Ralph mode via /ona:ralph command). |
> | `mcpIntegrationStatuses` | array of MCPIntegrationStatus | No | mcp\_integration\_statuses contains the status of all MCP integrations used by this agent execution |
> | `waitingInfo` | WaitingInfo | No | waiting\_info is set when phase is PHASE\_WAITING\_FOR\_INPUT and the agent has registered interests (timers, sub-agent completions, user messages). |
> | `terminalId` | string | No | terminal\_id is the ID of the terminal running the agent, if the agent runs as a terminal service (runsOn: terminal). |
> | `goal` | Goal | No | goal projects the current agent goal, if any. |
> | `codexSettings` | CodexSettings | No | codex\_settings contains runtime effective settings reported by the Codex app agent. |
> | `subagents` | array of Subagent | No | |

> [accordion] Phase
>
> | Value | Number | Description |
> | - | -: | - |
> | `PHASE_UNSPECIFIED` | 0 | The phase is not set. |
> | `PHASE_PENDING` | 10 | The agent run is pending. |
> | `PHASE_RUNNING` | 20 | The agent run is active. |
> | `PHASE_WAITING_FOR_INPUT` | 30 | The agent run is waiting for input. |
> | `PHASE_STOPPED` | 40 | The agent run is inactive. |

> [accordion] AgentExecutionFailureReason
>
> AgentExecutionFailureReason represents the reason why an agent execution failed
>
> | Value | Number | Description |
> | - | -: | - |
> | `AGENT_EXECUTION_FAILURE_REASON_UNSPECIFIED` | 0 | |
> | `AGENT_EXECUTION_FAILURE_REASON_ENVIRONMENT` | 1 | The agent execution failed due to environment issues |
> | `AGENT_EXECUTION_FAILURE_REASON_SERVICE` | 2 | The agent execution failed due to service issues |
> | `AGENT_EXECUTION_FAILURE_REASON_LLM_INTEGRATION` | 3 | The agent execution failed due to LLM integration issues |
> | `AGENT_EXECUTION_FAILURE_REASON_INTERNAL` | 4 | **Deprecated.** Deprecated: The agent execution failed due to internal errors Use AGENT\_EXECUTION\_FAILURE\_REASON\_AGENT\_EXECUTION instead |
> | `AGENT_EXECUTION_FAILURE_REASON_AGENT_EXECUTION` | 5 | The agent execution failed due to agent execution errors |

> [accordion] AgentExecutionRole
>
> AgentExecutionRole represents the role of an agent execution
>
> | Value | Number | Description |
> | - | -: | - |
> | `AGENT_EXECUTION_ROLE_UNSPECIFIED` | 0 | |
> | `AGENT_EXECUTION_ROLE_DEFAULT` | 1 | Default role for agent executions |
> | `AGENT_EXECUTION_ROLE_WORKFLOW` | 2 | Workflow role for agent executions that are part of a workflow |

> [accordion] AgentMode
>
> AgentMode defines the operational mode of an agent
>
> | Value | Number | Description |
> | - | -: | - |
> | `AGENT_MODE_UNSPECIFIED` | 0 | Default execution mode - standard agent behavior |
> | `AGENT_MODE_EXECUTION` | 1 | Execution mode - agent performs tasks and makes changes |
> | `AGENT_MODE_PLANNING` | 2 | Planning mode - agent focuses on analysis and planning |
> | `AGENT_MODE_RALPH` | 3 | Ralph mode - autonomous planning and implementation mode |
> | `AGENT_MODE_SPEC` | 4 | Spec mode - planning phase followed by interactive implementation |
> | `AGENT_MODE_GOAL` | 5 | Goal mode - agent treats the user input as a goal objective |

> [accordion] SupportedModel
>
> SupportedModel enumerates the LLM models available for agent executions
>
> | Value | Number | Description |
> | - | -: | - |
> | `SUPPORTED_MODEL_UNSPECIFIED` | 0 | |
> | `SUPPORTED_MODEL_SONNET_3_5` | 1 | |
> | `SUPPORTED_MODEL_SONNET_3_7` | 2 | |
> | `SUPPORTED_MODEL_SONNET_3_7_EXTENDED` | 3 | |
> | `SUPPORTED_MODEL_SONNET_4` | 4 | |
> | `SUPPORTED_MODEL_SONNET_4_EXTENDED` | 5 | |
> | `SUPPORTED_MODEL_SONNET_4_5` | 8 | |
> | `SUPPORTED_MODEL_SONNET_4_5_EXTENDED` | 9 | |
> | `SUPPORTED_MODEL_SONNET_4_6` | 18 | |
> | `SUPPORTED_MODEL_SONNET_4_6_EXTENDED` | 19 | |
> | `SUPPORTED_MODEL_SONNET_5` | 32 | |
> | `SUPPORTED_MODEL_OPUS_4` | 6 | |
> | `SUPPORTED_MODEL_OPUS_4_EXTENDED` | 7 | |
> | `SUPPORTED_MODEL_OPUS_4_5` | 14 | |
> | `SUPPORTED_MODEL_OPUS_4_5_EXTENDED` | 15 | |
> | `SUPPORTED_MODEL_OPUS_4_6` | 16 | |
> | `SUPPORTED_MODEL_OPUS_4_6_EXTENDED` | 17 | |
> | `SUPPORTED_MODEL_OPUS_4_7` | 22 | |
> | `SUPPORTED_MODEL_OPUS_4_8` | 31 | |
> | `SUPPORTED_MODEL_HAIKU_4_5` | 21 | |
> | `SUPPORTED_MODEL_OPENAI_4O` | 10 | |
> | `SUPPORTED_MODEL_OPENAI_4O_MINI` | 11 | |
> | `SUPPORTED_MODEL_OPENAI_O1` | 12 | |
> | `SUPPORTED_MODEL_OPENAI_O1_MINI` | 13 | |
> | `SUPPORTED_MODEL_OPENAI_AUTO` | 23 | SUPPORTED\_MODEL\_OPENAI\_AUTO flags a request as OpenAI-bound without encoding a specific model slug. The actual model is chosen by the client (today: native Codex via \~/.codex/config.toml) and captured from the upstream Responses-API response.model field for metering and rate-card lookup. This keeps the proto stable across OpenAI model-catalog churn. Reserved numbers 24-30 are intentionally left free for future OpenAI routing sentinels if we ever need to distinguish sub-families. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.