Skip to main content
POST
/
v2
/
agents
/
execution
/
list
List Agent Executions
curl --request POST \
  --url https://api.velt.dev/v2/agents/execution/list \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "agentId": "<string>",
    "documentId": "<string>",
    "organizationId": "<string>",
    "status": "<string>",
    "pageSize": 123,
    "cursor": "<string>",
    "orderDirection": "<string>"
  }
}
'
{
  "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
  }
}
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

​
x-velt-api-key
string
required
Your API key.
​
x-velt-auth-token
string
required
Your Auth Token.

​
Body

​
Params

​
data
object
required

​
Example Requests

​
List the most recent executions for an agent

{
  "data": {
    "agentId": "abc123def456",
    "pageSize": 50
  }
}

​
Paginate to the next page

{
  "data": {
    "agentId": "abc123def456",
    "pageSize": 50,
    "cursor": "eyJvZmZzZXQiOjUwfQ=="
  }
}

​
List failed executions for a document, oldest first

{
  "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

{
  "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

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "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
  }
}