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>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/execution/list"
payload = { "data": {
"agentId": "<string>",
"documentId": "<string>",
"organizationId": "<string>",
"status": "<string>",
"pageSize": 123,
"cursor": "<string>",
"orderDirection": "<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>',
documentId: '<string>',
organizationId: '<string>',
status: '<string>',
pageSize: 123,
cursor: '<string>',
orderDirection: '<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>',
'documentId' => '<string>',
'organizationId' => '<string>',
'status' => '<string>',
'pageSize' => 123,
'cursor' => '<string>',
'orderDirection' => '<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 \"documentId\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"status\": \"<string>\",\n \"pageSize\": 123,\n \"cursor\": \"<string>\",\n \"orderDirection\": \"<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 \"documentId\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"status\": \"<string>\",\n \"pageSize\": 123,\n \"cursor\": \"<string>\",\n \"orderDirection\": \"<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 \"documentId\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"status\": \"<string>\",\n \"pageSize\": 123,\n \"cursor\": \"<string>\",\n \"orderDirection\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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
}
}
Executions
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.
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>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/execution/list"
payload = { "data": {
"agentId": "<string>",
"documentId": "<string>",
"organizationId": "<string>",
"status": "<string>",
"pageSize": 123,
"cursor": "<string>",
"orderDirection": "<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>',
documentId: '<string>',
organizationId: '<string>',
status: '<string>',
pageSize: 123,
cursor: '<string>',
orderDirection: '<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>',
'documentId' => '<string>',
'organizationId' => '<string>',
'status' => '<string>',
'pageSize' => 123,
'cursor' => '<string>',
'orderDirection' => '<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 \"documentId\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"status\": \"<string>\",\n \"pageSize\": 123,\n \"cursor\": \"<string>\",\n \"orderDirection\": \"<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 \"documentId\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"status\": \"<string>\",\n \"pageSize\": 123,\n \"cursor\": \"<string>\",\n \"orderDirection\": \"<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 \"documentId\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"status\": \"<string>\",\n \"pageSize\": 123,\n \"cursor\": \"<string>\",\n \"orderDirection\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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
string
required
Your API key.
string
required
Your Auth Token.
Body
Params
object
required
Show properties
Show properties
string
Filter to executions of a single agent.
string
Filter by the client document ID the execution ran against.
string
Filter by the organization ID the execution ran under.
string
Filter by execution status. One of:
running / passed / failed / error / skipped.integer
1 to 500. Maximum number of executions to return in this page. Defaults to 50.
string
Pass back the previous response’s
nextCursor to fetch the next page.string
default:"desc"
Sort direction by
startedAt. One of: asc / desc. Defaults to desc (newest first).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
}
}
Was this page helpful?
⌘I

