> ## 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`](/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](/docs/api-reference#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= curl --request POST \ --url "$ONA_HOST/api/gitpod.v1.AgentService/GetAgentExecution" \ --header "Authorization: Bearer $ONA_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "agentExecutionId": "" }' ``` ```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="", ) 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: "", }); 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: "", }) 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": "" } ``` ## 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 `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 | `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. | `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. | `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 | | | 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. | 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 | 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 | 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 | 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. |