List Executions

POST /v2/agents/execution/list

List Executions

cURL

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>",
    "organizationId": "<string>",
    "documentId": "<string>",
    "pageSize": 123,
    "pageToken": "<string>"
  }
}
'

import requests

url = "https://api.velt.dev/v2/agents/execution/list"

payload = { "data": {
        "agentId": "<string>",
        "organizationId": "<string>",
        "documentId": "<string>",
        "pageSize": 123,
        "pageToken": "<string>"
    } }
headers = {
    "x-velt-api-key": "<x-velt-api-key>",
    "x-velt-auth-token": "<x-velt-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-velt-api-key': '<x-velt-api-key>',
    'x-velt-auth-token': '<x-velt-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      agentId: '<string>',
      organizationId: '<string>',
      documentId: '<string>',
      pageSize: 123,
      pageToken: '<string>'
    }
  })
};

fetch('https://api.velt.dev/v2/agents/execution/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.velt.dev/v2/agents/execution/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'agentId' => '<string>',
        'organizationId' => '<string>',
        'documentId' => '<string>',
        'pageSize' => 123,
        'pageToken' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-velt-api-key: <x-velt-api-key>",
    "x-velt-auth-token: <x-velt-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.velt.dev/v2/agents/execution/list"

	payload := strings.NewReader("{\n  \"data\": {\n    \"agentId\": \"<string>\",\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"pageSize\": 123,\n    \"pageToken\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
	req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/execution/list")
  .header("x-velt-api-key", "<x-velt-api-key>")
  .header("x-velt-auth-token", "<x-velt-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"agentId\": \"<string>\",\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"pageSize\": 123,\n    \"pageToken\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/agents/execution/list")

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

request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"agentId\": \"<string>\",\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"pageSize\": 123,\n    \"pageToken\": \"<string>\"\n  }\n}"

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

{
  "result": {
    "status": "success",
    "message": "Executions listed successfully",
    "data": {
      "executions": []
    }
  }
}

Use this API to fetch a paginated page of execution documents for the workspace, always ordered by startedAt descending (newest first). Designed for Console / Portal listing pages.

Get Execution remains the only way to fetch a single execution’s per-URL results subcollection — list never includes results. Each row is identical to the execution object from Get Execution (without includeResults), passed through metadata-stripping.

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

Filter combinations (whitelist). Exactly one of these three shapes is accepted. Every other combination — including {}, { organizationId } alone, { documentId } alone, { agentId, organizationId } (no docId), and { agentId, documentId } (no orgId) — is rejected with INVALID_ARGUMENT.

1. { agentId } — all executions of a single agent across the workspace.
2. { organizationId, documentId } — all executions on a single document (any agent).
3. { agentId, organizationId, documentId } — executions of a single agent on a single document.

Params

data · object · required

Show properties

agentId · string

Non-empty, non-whitespace. Required in combos #1 and #3; forbidden in combo #2.

organizationId · string

Non-empty, non-whitespace. Required in combos #2 and #3; forbidden in combo #1. Server-hashed before the query.

documentId · string

Non-empty, non-whitespace. Required in combos #2 and #3; forbidden in combo #1. Server-hashed before the query.

pageSize · number

Integer 1..100. Default 20. > 100 is rejected.

pageToken · string

Opaque cursor returned as data.nextPageToken on a prior call. Continues strictly after the cursor execution in startedAt-desc order.

Example Requests

1. Org + doc, first page (combo #2)

{
  "data": {
    "organizationId": "org_001",
    "documentId": "doc_001",
    "pageSize": 20
  }
}

2. Next page via cursor

{
  "data": {
    "organizationId": "org_001",
    "documentId": "doc_001",
    "pageSize": 20,
    "pageToken": "<opaque-token-from-previous-response>"
  }
}

3. Agent only (combo #1)

{
  "data": {
    "agentId": "agent_brand_check"
  }
}

4. All three (combo #3)

{
  "data": {
    "agentId": "agent_brand_check",
    "organizationId": "org_001",
    "documentId": "doc_001",
    "pageSize": 50
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Executions listed successfully",
    "data": {
      "executions": [
        {
          "id": "exec_1711900000000_abc123def456",
          "agentId": "agent_brand_check",
          "agentName": "Brand Consistency Checker",
          "agentVersion": 3,
          "config": { "seedUrl": "https://example.com", "crossPageExecute": true, "maxUrlsToProcess": 25 },
          "status": "passed",
          "startedAt": 1711900000000,
          "completedAt": 1711900150000,
          "durationMs": 150000,
          "trigger": "standalone",
          "ranBy": { "userId": "user_123", "name": "Jane Doe", "email": "[e-mail]" },
          "resultsSummary": { "totalFindings": 7, "totalAnnotationsCreated": 5, "urlsProcessed": 12, "urlsWithFindings": 5 },
          "llmModel": "claude/claude-sonnet-4-6",
          "tokenUsage": { "promptTokens": 12500, "completionTokens": 3200, "totalTokens": 15700 }
        }
      ],
      "nextPageToken": "<opaque-token>"
    }
  }
}

Field	Type	Description
data.executions	object[]	Page of execution documents (same shape as Get Execution, without results).
data.nextPageToken	string	Opaque cursor for the next page. Omitted entirely (key absent) when the result set is fully consumed.

Failure Response

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

Errors:

• INVALID_ARGUMENT — filter combo violates the 3-shape whitelist; pageSize out of range; pageToken empty/malformed/undecryptable; or pageToken references a now-deleted execution.
• NOT_FOUND — workspace store database could not be resolved.

{
  "result": {
    "status": "success",
    "message": "Executions listed successfully",
    "data": {
      "executions": []
    }
  }
}