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

# List Agent Executions

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>