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

> Lists all agent runs matching the specified filter.

`Unary` · [`Agents`](/docs/api-reference/generated/agent/overview)

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:

  ```yaml theme={null}
  filter:
    agentIds: ["b8a64cfa-43e2-4b9d-9fb3-07edc63f5971"]
  pagination:
    pageSize: 10
  ```

## Endpoint

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

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

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```

  ```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.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)
  }
  ```

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

## Request

`gitpod.v1.ListAgentExecutionsRequest`

| Field        | Type                                                           | Required | Description |
| ------------ | -------------------------------------------------------------- | -------- | ----------- |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request)        | No       |             |
| `filter`     | [Filter](#type-gitpod-v1-list-agent-executions-request-filter) | No       |             |

## Response

`gitpod.v1.ListAgentExecutionsResponse`

| Field             | Type                                                       | Required | Description |
| ----------------- | ---------------------------------------------------------- | -------- | ----------- |
| `pagination`      | [PaginationResponse](#type-gitpod-v1-pagination-response)  | No       |             |
| `agentExecutions` | array of [AgentExecution](#type-gitpod-v1-agent-execution) | No       |             |

## Related types

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

<Accordion title="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>

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

<Accordion title="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>

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

<Accordion title="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>

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

<Accordion title="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>

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

<Accordion title="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](#enum-gitpod-v1-agent-execution-phase)             | No       | Constraints: `repeated.max_items=25, repeated.min_items=0`.                                                                                                                                                                               |
  | `roles`             | array of [AgentExecutionRole](#enum-gitpod-v1-agent-execution-role) | 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`. |
</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="enum-gitpod-v1-agent-execution-phase" />

<Accordion title="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>

<a id="enum-gitpod-v1-agent-execution-failure-reason" />

<Accordion title="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>

<a id="enum-gitpod-v1-agent-execution-role" />

<Accordion title="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>

<a id="enum-gitpod-v1-agent-mode" />

<Accordion title="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>

<a id="enum-gitpod-v1-supported-model" />

<Accordion title="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. |
</Accordion>