> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# List agent executions

GET https://api.runtype.com/v1/agents/{id}/executions

Deprecated: use `GET /v1/runs?agentId={id}`, the single run list for every agent and flow run, including runs dispatched with `storeResults: false` that write no row here. This endpoint stays available and unchanged. It reads the control-plane `agent_executions` table only. List execution history for an agent with cursor pagination. Rows include `finalOutput` by default; pass `view=compact` for the lighter projection that omits it and previews long strings. Supports cross-agent subagent drill-down via parentExecutionId or executionId filters.

Reference: https://docs.runtype.com/api-reference/runtype-api/agents/list-agent-executions

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Path parameters

- `id` (string, required)

### Query parameters

- `limit` (string, optional)
- `cursor` (string, optional)
- `includeCount` (string, optional)
- `status` (enum, optional)
  - Allowed values: `queued`, `running`, `paused`, `completed`, `failed`, `cancelled`, `interrupted`
- `surfaceType` (string, optional)
- `agentSource` (enum, optional) — Only runs recorded with this agent source; `external` selects runs ingested from outside Runtype (OTLP / compatibility ingest).
  - Allowed values: `saved`, `inline`, `dynamic`, `external`
- `from` (string, optional)
- `to` (string, optional)
- `parentExecutionId` (string, optional)
- `executionId` (string, optional)
- `view` (enum, optional) — Response representation. `full` (default) preserves complete values and includes each row's `finalOutput`; `compact` omits `finalOutput` and shortens every remaining string value longer than 100 characters to a 100-character preview followed by `…`.
  - Allowed values: `full`, `compact`

## Response

### 200

Paginated list of agent executions

- `data` (list of V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItems, required)
- `pagination` (Pagination, required)

## Errors

### 400 Bad Request Error

Invalid parameters

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 403 Forbidden Error

Insufficient permissions

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 404 Not Found Error

Agent not found

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 500 Internal Server Error

Internal server error

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

## Types

### V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItems

- `agentId` (string, required, nullable)
- `agentSource` (string, required, nullable)
- `agentTargetResolution` (enum, required) — How the run selected its definition: `alias` or `version` for a request that named a selector, `legacy-live-row` for a run that read the mutable agent row.
  - Allowed values: `alias`, `version`, `legacy-live-row`
- `agentVersion` (V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItemsAgentVersion, required, nullable) — Version number and label for `agentVersionId`, joined from `agent_versions`. `null` exactly when `agentVersionId` is `null`.
- `agentVersionId` (string, required, nullable) — The `agent_versions` row this run was recorded against, or `null`. `null` means the surface that admitted the run stamps no version (A2A, Product API, A2A pause admission and the Product MCP capability path record none today) or the run predates version stamping. It is never a claim that the run executed an unversioned configuration.
- `budgetExhausted` (boolean, required, nullable) — Whether the agent loop ended by exhausting its `maxTurns` budget. Read this rather than inferring truncation from `stopReason`: a single-turn loop publishes `end_turn` on a budget end to preserve its original payload shape, and several clean success paths publish that same value. `null` means UNKNOWN — a run recorded before this field existed, or one executed by a lane that reports no per-iteration breakdown (external agents, Claude Managed) — and must not be read as `false`.
- `cancelRequestedAt` (string, required, nullable)
- `completedAt` (string, required, nullable)
- `conversationId` (string, required, nullable) — The conversation thread this run belongs to, so consumers can group a multi-turn conversation's runs without a per-run log query. This is the run's OWN thread, distinct from `parentConversationId` (subagent lineage, the conversation of the run that spawned it). `null` on stateless surfaces (webhook, schedule, eval, one-shot API) and on runs persisted before the column existed.
- `createdAt` (string, required)
- `executionId` (string, required)
- `executionMode` (enum, required)
  - Allowed values: `attached`, `detached`
- `expiresAt` (string, required, nullable)
- `id` (string, required)
- `iterations` (integer, required, nullable)
- `lastHeartbeatAt` (string, required, nullable)
- `notificationMode` (enum, required)
  - Allowed values: `none`, `narrate`, `react`
- `otelProducer` (V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItemsOtelProducer, required, nullable) — What instrumentation produced an ingested run, as the OTLP ingest resolved it: the adapter a producer named itself as (`runtype.adapter.name`) and every normalizer that claimed the trace. An empty `normalizers` array states that nothing claimed it, which is what a producer already speaking canonical GenAI semantic conventions looks like. `null` means the producer was never recorded (a hosted run, or a run ingested before this was persisted) and must not be read as "identified as nothing".
- `parentAgentId` (string, required, nullable)
- `parentConversationId` (string, required, nullable)
- `parentExecutionId` (string, required, nullable)
- `parentToolCallId` (string, required, nullable)
- `pendingApproval` (V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItemsPendingApproval, required, nullable)
- `retryOfExecutionId` (string, required, nullable)
- `rootExecutionId` (string, required, nullable)
- `startedAt` (string, required, nullable)
- `status` (enum, required)
  - Allowed values: `queued`, `running`, `paused`, `completed`, `failed`, `cancelled`, `interrupted`
- `stopReason` (string, required, nullable)
- `surfaceType` (string, required, nullable)
- `totalCost` (string, required, nullable)
- `agentSpec` (any, optional)
- `finalOutput` (any, optional) — The run's final output. Present by default; omitted when `view=compact`.
- `inputMessages` (any, optional)
- `progress` (any, optional)
- `signals` (V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItemsSignals, optional) — Trace signal status and fired keys. Omitted until the organization binds a signal set.
- `totalTokens` (any, optional)

### Pagination

- `currentOffset` (integer, required)
- `hasMore` (boolean, required)
- `hasPrev` (boolean, required)
- `limit` (integer, required)
- `nextCursor` (string, required, nullable)
- `prevCursor` (string, required, nullable)
- `currentPage` (integer, optional)
- `totalCount` (integer, optional)
- `totalPages` (integer, optional)

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItemsAgentVersion

Version number and label for `agentVersionId`, joined from `agent_versions`. `null` exactly when `agentVersionId` is `null`.

- `id` (string, required)
- `label` (string, required, nullable)
- `versionNumber` (integer, required)

### V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItemsOtelProducer

What instrumentation produced an ingested run, as the OTLP ingest resolved it: the adapter a producer named itself as (`runtype.adapter.name`) and every normalizer that claimed the trace. An empty `normalizers` array states that nothing claimed it, which is what a producer already speaking canonical GenAI semantic conventions looks like. `null` means the producer was never recorded (a hosted run, or a run ingested before this was persisted) and must not be read as "identified as nothing".

- `adapterName` (string, optional)
- `adapterVersion` (string, optional)
- `normalizers` (list of string, optional)

### V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItemsPendingApproval

- `approvalId` (string, required)
- `requestedAt` (string, required)
- `toolCallId` (string, required)
- `toolName` (string, required)
- `toolType` (string, required)
- `description` (string, optional)
- `parameters` (any, optional)
- `reason` (string, optional)
- `timeout` (double, optional)

### V1AgentsIdExecutionsGetResponsesContentApplicationJsonSchemaDataItemsSignals

Trace signal status and fired keys. Omitted until the organization binds a signal set.

- `fired` (list of string, required)
- `status` (enum, required)
  - Allowed values: `complete`, `pending`, `partial`, `none`, `unavailable`

## Examples

**Response**

```json
{
  "data": [
    {
      "agentId": "string",
      "agentSource": "string",
      "agentTargetResolution": "alias",
      "agentVersion": {
        "id": "string",
        "label": "string",
        "versionNumber": 1
      },
      "agentVersionId": "string",
      "budgetExhausted": true,
      "cancelRequestedAt": "string",
      "completedAt": "string",
      "conversationId": "string",
      "createdAt": "string",
      "executionId": "string",
      "executionMode": "attached",
      "expiresAt": "string",
      "id": "string",
      "iterations": 1,
      "lastHeartbeatAt": "string",
      "notificationMode": "none",
      "otelProducer": {
        "adapterName": "string",
        "adapterVersion": "string",
        "normalizers": [
          "string"
        ]
      },
      "parentAgentId": "string",
      "parentConversationId": "string",
      "parentExecutionId": "string",
      "parentToolCallId": "string",
      "pendingApproval": {
        "approvalId": "string",
        "requestedAt": "string",
        "toolCallId": "string",
        "toolName": "string",
        "toolType": "string",
        "description": "string",
        "reason": "string",
        "timeout": 1.1
      },
      "retryOfExecutionId": "string",
      "rootExecutionId": "string",
      "startedAt": "string",
      "status": "queued",
      "stopReason": "string",
      "surfaceType": "string",
      "totalCost": "string",
      "finalOutput": null,
      "signals": {
        "fired": [
          "string"
        ],
        "status": "complete"
      }
    }
  ],
  "pagination": {
    "currentOffset": 1,
    "hasMore": true,
    "hasPrev": true,
    "limit": 1,
    "nextCursor": "string",
    "prevCursor": "string",
    "currentPage": 1,
    "totalCount": 1,
    "totalPages": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.runtype.com/v1/agents/id/executions"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.runtype.com/v1/agents/id/executions';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/agents/id/executions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/agents/id/executions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.runtype.com/v1/agents/id/executions")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.runtype.com/v1/agents/id/executions', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/agents/id/executions");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/agents/id/executions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```