> ## Documentation Index
> Fetch the complete documentation index at: https://velt-mintlify-e6426361.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List agent executions (v2)

> List AI agent execution runs with status, timing, and metadata using the Velt v2 REST API to monitor agent activity, debug runs, and audit usage.

Use this API to paginate through an agent's execution history without fetching each execution individually. Filter by `agentId`, `documentId`, `organizationId`, and/or `status`, page with `pageSize` + `cursor`, and control sort order with `orderDirection`.

# Endpoint

`POST https://api.velt.dev/v2/agents/execution/list`

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string">
      Filter to executions of a single agent.
    </ParamField>

    <ParamField body="documentId" type="string">
      Filter by the client document ID the execution ran against.
    </ParamField>

    <ParamField body="organizationId" type="string">
      Filter by the organization ID the execution ran under.
    </ParamField>

    <ParamField body="status" type="string">
      Filter by execution status. One of: `running` / `passed` / `failed` / `error` / `skipped`.
    </ParamField>

    <ParamField body="pageSize" type="integer">
      1 to 500. Maximum number of executions to return in this page. Defaults to 50.
    </ParamField>

    <ParamField body="cursor" type="string">
      Pass back the previous response's `nextCursor` to fetch the next page.
    </ParamField>

    <ParamField body="orderDirection" type="string" default="desc">
      Sort direction by `startedAt`. One of: `asc` / `desc`. Defaults to `desc` (newest first).
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### List the most recent executions for an agent

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "pageSize": 50
  }
}
```

#### Paginate to the next page

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "pageSize": 50,
    "cursor": "eyJvZmZzZXQiOjUwfQ=="
  }
}
```

#### List failed executions for a document, oldest first

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "documentId": "doc_001",
    "status": "failed",
    "orderDirection": "asc"
  }
}
```

# Response

`result.items` is an array of execution documents ordered by `startedAt`, each including `status` and a human-readable `message`, so you can enumerate prior runs without per-execution lookups. `nextCursor` and `hasMore` drive pagination: pass `nextCursor` back as `cursor` while `hasMore` is `true`. An empty `items` array is returned when no executions match.

#### Success Response

```JSON theme={null}
{
  "result": {
    "items": [
      {
        "id": "exec_1711900000000_abc123def456",
        "agentId": "abc123def456",
        "agentName": "Brand Consistency Checker",
        "agentVersion": 3,
        "status": "passed",
        "message": "Found 7 issues across 12 pages. 5 annotations created.",
        "startedAt": 1711900000000,
        "completedAt": 1711900150000,
        "durationMs": 150000,
        "trigger": "standalone"
      },
      {
        "id": "exec_1711800000000_abc123def456",
        "agentId": "abc123def456",
        "agentName": "Brand Consistency Checker",
        "agentVersion": 3,
        "status": "running",
        "message": "Execution in progress",
        "startedAt": 1711800000000,
        "completedAt": null,
        "durationMs": null,
        "trigger": "standalone"
      }
    ],
    "nextCursor": "eyJvZmZzZXQiOjUwfQ==",
    "hasMore": true
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "items": [
        {
          "id": "exec_1711900000000_abc123def456",
          "agentId": "abc123def456",
          "agentName": "Brand Consistency Checker",
          "agentVersion": 3,
          "status": "passed",
          "message": "Found 7 issues across 12 pages. 5 annotations created.",
          "startedAt": 1711900000000,
          "completedAt": 1711900150000,
          "durationMs": 150000,
          "trigger": "standalone"
        }
      ],
      "nextCursor": "eyJvZmZzZXQiOjUwfQ==",
      "hasMore": true
    }
  }
  ```
</ResponseExample>