Unary · Agents
Lists all agent runs matching the specified filter.
Use this method to track multiple agent runs and their associated resources. Results are ordered by their creation time with the newest first.
Examples
-
List agent runs by agent ID:
filter: agentIds: ["b8a64cfa-43e2-4b9d-9fb3-07edc63f5971"] pagination: pageSize: 10
Endpoint
POST /api/gitpod.v1.AgentService/ListAgentExecutions
https://app.ona.com with that domain.
Request example
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.AgentService/ListAgentExecutions" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"pagination": {
"pageSize": 1
}
}'
import gitpod.v1.agent_pb2 as agent_pb2
import gitpod.v1.pagination_pb2 as pagination_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = agent_pb2.ListAgentExecutionsRequest(
pagination=pagination_pb2.PaginationRequest(
page_size=1,
),
)
response = ona.services.agent.list_agent_executions(request)
print(response)
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListAgentExecutionsRequestSchema } from "@gitpod/sdk/gitpod/v1/agent_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListAgentExecutionsRequestSchema, {
pagination: {
pageSize: 1,
},
});
const response = await ona.services.agent.listAgentExecutions(request);
console.log(response);
}
main().catch(console.error);
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.ListAgentExecutionsRequest{
Pagination: &gitpodpb.PaginationRequest{
PageSize: 1,
},
})
response, err := ona.Services.Agent.ListAgentExecutions(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
{
"pagination": {
"pageSize": 1
}
}
Request
gitpod.v1.ListAgentExecutionsRequest
| Field | Type | Required | Description |
|---|---|---|---|
pagination | PaginationRequest | No | |
filter | Filter | No |
Response
gitpod.v1.ListAgentExecutionsResponse
| Field | Type | Required | Description |
|---|---|---|---|
pagination | PaginationResponse | No | |
agentExecutions | array of AgentExecution | No |
Related types
AgentExecution
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 | No | Metadata is data associated with this agent that’s required for other parts of Gitpod to function |
spec | Spec | No | Spec is the configuration of the agent that’s required for the runner to start the agent |
status | Status | No | Status is the current status of the agent |
Metadata
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 | 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. |
Spec
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 | 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. |
Status
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 | 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 | 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 | 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 | 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 |
Filter
Filter
gitpod.v1.ListAgentExecutionsRequest.Filter| Field | Type | Required | Description |
|---|---|---|---|
agentIds | array of string | No | Constraints: repeated.max_items=25, repeated.min_items=0. |
projectIds | array of string | No | Constraints: repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0. |
environmentIds | array of string | No | Constraints: repeated.max_items=25, repeated.min_items=0. |
creatorIds | array of string | No | Constraints: repeated.max_items=25, repeated.min_items=0. |
statusPhases | array of Phase | No | Constraints: repeated.max_items=25, repeated.min_items=0. |
roles | array of AgentExecutionRole | No | Constraints: repeated.items.enum.defined_only=true, repeated.max_items=25, repeated.min_items=0. |
annotations | map of string to string | No | annotations filters by key-value pairs. Only executions containing all specified annotations (with matching values) are returned. |
sessionIds | array of string | No | session_ids filters the response to only executions belonging to the specified sessions Constraints: repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0. |
agentExecutionIds | array of string | No | agent_execution_ids filters the response to only the specified executions. Useful for checking existence of a known set of execution IDs. Constraints: repeated.items.string.uuid=true, repeated.max_items=100, repeated.min_items=0. |
PaginationRequest
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 |
PaginationResponse
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 |
Phase
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. |
AgentExecutionFailureReason
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 |
AgentExecutionRole
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 |
AgentMode
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 |
SupportedModel
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. |