Get Execution
curl --request POST \
--url https://api.velt.dev/v2/agents/execution/get \
--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": {
"executionId": "<string>",
"includeResults": true
}
}
'import requests
url = "https://api.velt.dev/v2/agents/execution/get"
payload = { "data": {
"executionId": "<string>",
"includeResults": True
} }
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: {executionId: '<string>', includeResults: true}})
};
fetch('https://api.velt.dev/v2/agents/execution/get', 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/get",
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' => [
'executionId' => '<string>',
'includeResults' => true
]
]),
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/get"
payload := strings.NewReader("{\n \"data\": {\n \"executionId\": \"<string>\",\n \"includeResults\": true\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/get")
.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 \"executionId\": \"<string>\",\n \"includeResults\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/execution/get")
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 \"executionId\": \"<string>\",\n \"includeResults\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": {
"id": "exec_1711900000000_abc123def456",
"status": "running",
"startedAt": 1711900000000,
"completedAt": null,
"durationMs": null
}
}
}
}
Execution
Get Execution
POST
/
v2
/
agents
/
execution
/
get
Get Execution
curl --request POST \
--url https://api.velt.dev/v2/agents/execution/get \
--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": {
"executionId": "<string>",
"includeResults": true
}
}
'import requests
url = "https://api.velt.dev/v2/agents/execution/get"
payload = { "data": {
"executionId": "<string>",
"includeResults": True
} }
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: {executionId: '<string>', includeResults: true}})
};
fetch('https://api.velt.dev/v2/agents/execution/get', 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/get",
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' => [
'executionId' => '<string>',
'includeResults' => true
]
]),
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/get"
payload := strings.NewReader("{\n \"data\": {\n \"executionId\": \"<string>\",\n \"includeResults\": true\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/get")
.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 \"executionId\": \"<string>\",\n \"includeResults\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/execution/get")
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 \"executionId\": \"<string>\",\n \"includeResults\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": {
"id": "exec_1711900000000_abc123def456",
"status": "running",
"startedAt": 1711900000000,
"completedAt": null,
"durationMs": null
}
}
}
}
Use this API to fetch an execution document by ID. This is the polling endpoint: poll until
Execution document field reference:
Success Response (with results,
When
Per-URL result fields:
Finding fields (
Errors:
execution.status !== "running". Set includeResults: true to also fetch the per-URL findings subcollection.
Endpoint
POST https://api.velt.dev/v2/agents/execution/get
Headers
Your API key.
Your Auth Token.
Body
Params
Show properties
Show properties
Min 1 char. Execution ID returned from Run Execution.
Include the full per-URL results subcollection. Default:
false.Example Requests
1. Poll status only
{
"data": {
"executionId": "exec_1711900000000_abc123def456"
}
}
2. Fetch with full results
{
"data": {
"executionId": "exec_1711900000000_abc123def456",
"includeResults": true
}
}
Response
Success Response (execution document)
{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": {
"id": "exec_1711900000000_abc123def456",
"agentId": "abc123def456",
"agentName": "Brand Consistency Checker",
"agentVersion": 3,
"metadata": {
"organizationId": "org_001",
"documentId": "doc_001"
},
"config": {
"seedUrl": "https://example.com",
"crossPageExecute": true,
"maxUrlsToProcess": 25,
"deviceType": "desktop",
"crawlerConfig": { "maxPages": 100, "timeout": 300000, "maxDepth": 0 }
},
"status": "passed",
"startedAt": 1711900000000,
"completedAt": 1711900150000,
"durationMs": 150000,
"trigger": "standalone",
"workflowExecutionId": null,
"previousExecutionId": null,
"ranBy": { "userId": "user_123", "name": "Jane Doe", "email": "jane@example.com" },
"resultsSummary": {
"totalFindings": 7,
"totalAnnotationsCreated": 7,
"urlsProcessed": 12,
"urlsWithFindings": 5,
"issuesCreated": 7,
"summary": "Found 7 issues across 12 pages. 7 annotations created."
},
"crawlerResults": { "status": "completed", "totalUrlsFound": 12, "duration": 45000, "pagesVisited": 12 },
"llmModel": "claude/claude-sonnet-4-6",
"tokenUsage": { "promptTokens": 12500, "completionTokens": 3200, "thoughtsTokens": 0, "totalTokens": 15700 }
}
}
}
}
| Field | Type | Description |
|---|---|---|
id | string | Execution ID (Firestore doc ID). |
agentId | string | Agent that was executed. |
agentName | string | Denormalized agent display name. |
agentVersion | number | Agent config version at execution time (pinned). |
metadata.organizationId | string | The organizationId you passed on Run Execution. Empty string when absent. |
metadata.documentId | string | The documentId you passed on Run Execution. Empty string when absent. |
config.seedUrl | string | The seed URL provided by the user. |
config.crossPageExecute | boolean | Whether cross-page mode was used. |
config.maxUrlsToProcess | number | Max URLs limit. |
config.deviceType | string | Device mode emulated for this execution: "mobile" or "desktop". Default: "desktop". |
config.crawlerConfig | object | undefined | Crawler config (only when crossPageExecute: true). |
status | string | "running", "passed", "failed", "partial", "error", or "skipped". See statuses. |
startedAt | number | Epoch ms when execution started. |
completedAt | number | null | Epoch ms when completed. Null while running. |
durationMs | number | null | Total duration in ms. Null while running. |
error | object | undefined | Populated when any URL/batch failed: on "error" or "partial" (and may co-exist with "failed"). |
error.code | string | Error code (TIMEOUT, LLM_ERROR, LLM_RATE_LIMITED, MALFORMED_RESPONSE, CRAWLER_ERROR, EXTRACTION_ERROR, POST_PROCESS_ERROR, INTERNAL). |
error.message | string | Human-readable error description. |
error.advisoryComment | string | undefined | Advisory comment text posted to the document. |
error.retryable | boolean | Whether this error can be retried. |
error.occurredAt | number | Epoch ms when the error occurred. |
trigger | string | "standalone" or "workflow". |
workflowExecutionId | string | null | Parent workflow execution ID (if workflow-triggered). |
previousExecutionId | string | null | Previous execution ID (set on reruns). |
ranBy | object | { userId, name, email } of who triggered. |
resultsSummary.totalFindings | number | Total findings (after guardrails filtering). |
resultsSummary.totalAnnotationsCreated | number | Annotations created. Re-runs first clear the prior run’s suggestions per URL (delete-and-recreate), so this counts the fresh annotations written by this run. |
resultsSummary.urlsProcessed | number | URLs that were processed. |
resultsSummary.urlsWithFindings | number | URLs that had at least one finding. |
resultsSummary.urlsErrored | number | undefined | URLs whose agent run failed. 0 < urlsErrored < urlsProcessed → partial; urlsErrored >= urlsProcessed (≥1 processed) → error. |
resultsSummary.erroredUrls | array | undefined | Bounded sample (≤50) of { url, message } for failing URLs. |
resultsSummary.issuesCreated | number | Equals totalFindings (backwards compat). |
resultsSummary.summary | string | null | Human-readable summary. Null while running. |
resultsSummary.matchResult | object | undefined | Legacy. Match-and-merge outcome ({ created, skipped, resolved }) written by the retired match-and-merge dedup. Present only on old execution documents; new executions use per-URL delete-and-recreate and never write this field. |
crawlerResults | object | undefined | Only populated when crossPageExecute: true. |
llmModel | string | undefined | LLM model used (e.g. "claude/claude-sonnet-4-6", "gemini/gemini-3-flash-preview"). |
tokenUsage | object | { promptTokens, completionTokens, thoughtsTokens, totalTokens }. |
The legacy execution-document fields
knowledgeRetrieved / knowledgeCached / degraded have been removed. Memory-RAG runtime signals now live only on the in-memory execution result and are consumed internally by the guardrails processor; they are not persisted on the execution document.Success Response (with results, includeResults: true)
When includeResults is true, a results array is included alongside execution:
{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": { "...same as above..." },
"results": [
{
"url": "https://example.com",
"urlHash": "a1b2c3d4e5f6",
"findings": [
{
"id": "finding-1",
"title": "Heading uses wrong font",
"description": "The h1 element uses 'Arial' instead of the brand font 'Inter'",
"severity": "high",
"category": "typography",
"targetText": "Welcome to Example",
"occurrence": 1,
"sourceUrl": "https://example.com",
"suggestion": "Change font-family to 'Inter' for the h1 element",
"htmlSelector": "h1.hero-title",
"htmlXpath": "/html/body/main/section[1]/h1",
"isPageLevel": false,
"issueType": "brand-font",
"confidence": 92
}
],
"findingCount": 1,
"annotationsCreated": 1,
"processedAt": 1711900050000
}
]
}
}
}
| Field | Type | Description |
|---|---|---|
url | string | The URL that was analyzed. |
urlHash | string | MD5 hash of the URL (Firestore doc ID). |
findings | object[] | Array of AgentFinding objects (see below). |
findingCount | number | Number of findings for this URL. |
annotationsCreated | number | Annotations created for this URL. |
processedAt | number | Epoch ms when this URL was processed. |
AgentFinding):
| Field | Type | Description |
|---|---|---|
id | string | Unique finding ID (e.g. "finding-1"). |
title | string | Short title/summary. |
description | string | Detailed description. |
severity | string | "critical", "high", "medium", "low", "info". |
category | string | Grouping tag (e.g. "accessibility", "seo", "content", "layout"). |
targetText | string | Exact DOM text. Empty string for image/non-text findings. |
occurrence | number | 1-based occurrence index of targetText on the page. |
sourceUrl | string | URL where the finding was detected. |
suggestion | string | Suggested fix. |
htmlSelector | string | CSS selector of the DOM element. |
htmlXpath | string | XPath of the DOM element. |
isPageLevel | boolean | true for visual/layout findings; false when targetText matches DOM text. |
issueType | string | Issue classification tag (e.g. "casing", "pii", "spelling", "broken-link"). |
confidence | number | 0–100 confidence score reported by the agent. |
commentId | string | Comment annotation ID (populated after annotation creation). |
source | string | "instructions" or "knowledge". |
Failure Response
{
"error": {
"message": "ERROR_MESSAGE",
"status": "NOT_FOUND"
}
}
NOT_FOUND (Execution not found: {executionId} or Store database not found).
{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": {
"id": "exec_1711900000000_abc123def456",
"status": "running",
"startedAt": 1711900000000,
"completedAt": null,
"durationMs": null
}
}
}
}
Was this page helpful?
⌘I

