Gitpod API Reference | Agents › List Agent Executions

Agents

agents

Methods

Create Agent Execution Conversation Token -> { token }

post/gitpod.v1.AgentService/CreateAgentExecutionConversationToken

Creates a token for conversation access with a specific agent run.

This method generates a temporary token that can be used to securely connect to an ongoing agent conversation, for example in a web UI.

Examples

Create a token to join an agent run conversation in a front-end application:
```
agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"
```

Create Prompt -> { prompt }

post/gitpod.v1.AgentService/CreatePrompt

Creates a new prompt.

Use this method to:

Define new prompts for templates or commands
Set up organization-wide prompt libraries

Delete Agent Execution -> unknown

post/gitpod.v1.AgentService/DeleteAgentExecution

Deletes an agent run.

Use this method to:

Clean up agent runs that are no longer needed

Examples

Delete an agent run by ID:

agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"

Delete Prompt -> unknown

post/gitpod.v1.AgentService/DeletePrompt

Deletes a prompt.

Use this method to:

Remove unused prompts

List Agent Executions -> AgentExecutionsPage<

AgentExecution

post/gitpod.v1.AgentService/ListAgentExecutions

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

query Parameters

token: string

Optional

pageSize: number

Optional

(maximum: 100, minimum: 0, default: 25)

Response fields

agentExecutions: Array<

AgentExecution

Optional

pagination: { nextToken }

Optional

Request example

curl https://app.gitpod.io/api/gitpod.v1.AgentService/ListAgentExecutions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

200Example

{
  "agentExecutions": [
    {
      "id": "id",
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "creator": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "description": "description",
        "name": "name",
        "role": "AGENT_EXECUTION_ROLE_UNSPECIFIED",
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "workflowActionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "spec": {
        "agentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "codeContext": {
          "contextUrl": {
            "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            "url": "https://example.com"
          },
          "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "pullRequest": {
            "id": "id",
            "author": "author",
            "fromBranch": "fromBranch",
            "repository": {
              "cloneUrl": "cloneUrl",
              "host": "host",
              "name": "name",
              "owner": "owner"
            },
            "title": "title",
            "toBranch": "toBranch",
            "url": "url"
          }
        },
        "desiredPhase": "PHASE_UNSPECIFIED",
        "limits": {
          "maxInputTokens": "maxInputTokens",
          "maxIterations": "maxIterations",
          "maxOutputTokens": "maxOutputTokens"
        },
        "mode": "AGENT_MODE_UNSPECIFIED",
        "session": "session",
        "specVersion": "specVersion"
      },
      "status": {
        "cachedCreationTokensUsed": "cachedCreationTokensUsed",
        "cachedInputTokensUsed": "cachedInputTokensUsed",
        "contextWindowLength": "contextWindowLength",
        "conversationUrl": "conversationUrl",
        "currentActivity": "currentActivity",
        "currentOperation": {
          "llm": {
            "complete": true
          },
          "retries": "retries",
          "session": "session",
          "toolUse": {
            "complete": true,
            "toolName": "x"
          }
        },
        "failureMessage": "failureMessage",
        "failureReason": "AGENT_EXECUTION_FAILURE_REASON_UNSPECIFIED",
        "inputTokensUsed": "inputTokensUsed",
        "iterations": "iterations",
        "judgement": "judgement",
        "outputs": {
          "foo": {
            "boolValue": true,
            "floatValue": 0,
            "intValue": "intValue",
            "stringValue": "stringValue"
          }
        },
        "outputTokensUsed": "outputTokensUsed",
        "phase": "PHASE_UNSPECIFIED",
        "session": "session",
        "statusVersion": "statusVersion",
        "supportedModel": "SUPPORTED_MODEL_UNSPECIFIED",
        "transcriptUrl": "transcriptUrl",
        "usedEnvironments": [
          {
            "createdByAgent": true,
            "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
          }
        ],
        "warningMessage": "warningMessage"
      }
    }
  ],
  "pagination": {
    "nextToken": "nextToken"
  }
}

List Prompts -> PromptsPage<

Prompt

post/gitpod.v1.AgentService/ListPrompts

Lists all prompts matching the specified criteria.

Use this method to find and browse prompts across your organization. Results are ordered by their creation time with the newest first.

Examples

List all prompts:

Retrieves all prompts with pagination.
```
pagination:
  pageSize: 10
```

Get Agent Execution -> { agentExecution }

post/gitpod.v1.AgentService/GetAgentExecution

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:

agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"

Get Prompt -> { prompt }

post/gitpod.v1.AgentService/GetPrompt

Gets details about a specific prompt including name, description, and prompt content.

Use this method to:

Retrieve prompt details for editing
Get prompt content for execution

Examples

Get prompt details:

promptId: "07e03a28-65a5-4d98-b532-8ea67b188048"

Send To Agent Execution -> unknown

post/gitpod.v1.AgentService/SendToAgentExecution

Sends user input to an active agent run.

This method is used to provide interactive or conversation-based input to an agent. The agent can respond with output blocks containing text, file changes, or tool usage requests.

Examples

Send a text message to an agent:

agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"
userInput:
  text:
    content: "Generate a report based on the latest logs."

Start Agent -> { agentExecutionId }

post/gitpod.v1.AgentService/StartAgent

Starts (or triggers) an agent run using a provided agent.

Use this method to:

Launch an agent based on a known agent

Examples

Start an agent with a project ID:

agentId: "b8a64cfa-43e2-4b9d-9fb3-07edc63f5971"
codeContext:
  projectId: "2d22e4eb-31da-467f-882c-27e21550992f"

Stop Agent Execution -> unknown

post/gitpod.v1.AgentService/StopAgentExecution

Stops an active agent execution.

Use this method to:

Stop an agent that is currently running
Prevent further processing or resource usage

Examples

Stop an agent execution by ID:

agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"

Update Prompt -> { prompt }

post/gitpod.v1.AgentService/UpdatePrompt

Updates an existing prompt.

Use this method to:

Modify prompt content or metadata
Change prompt type (template/command)

Domain types

AgentCodeContext = { contextUrl, environmentId, projectId, 1 more... }

AgentExecution = { id, metadata, spec, 1 more... }

AgentMode = "AGENT_MODE_UNSPECIFIED" | "AGENT_MODE_EXECUTION" | "AGENT_MODE_PLANNING"

AgentMode defines the operational mode of an agent

Prompt = { id, metadata, spec }

PromptMetadata = { createdAt, creator, description, 3 more... }

PromptSpec = { command, isCommand, isTemplate, 1 more... }

UserInputBlock = { text, id, createdAt }