Run Execution
curl --request POST \
--url https://api.velt.dev/v2/agents/execution/run \
--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>",
"url": "<string>",
"crossPageExecute": true,
"maxUrlsToProcess": 123,
"deviceType": "<string>",
"organizationId": "<string>",
"documentId": "<string>",
"trigger": "<string>",
"workflowExecutionId": "<string>",
"ranBy": {},
"userContext": {}
}
}
'import requests
url = "https://api.velt.dev/v2/agents/execution/run"
payload = { "data": {
"agentId": "<string>",
"url": "<string>",
"crossPageExecute": True,
"maxUrlsToProcess": 123,
"deviceType": "<string>",
"organizationId": "<string>",
"documentId": "<string>",
"trigger": "<string>",
"workflowExecutionId": "<string>",
"ranBy": {},
"userContext": {}
} }
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>',
url: '<string>',
crossPageExecute: true,
maxUrlsToProcess: 123,
deviceType: '<string>',
organizationId: '<string>',
documentId: '<string>',
trigger: '<string>',
workflowExecutionId: '<string>',
ranBy: {},
userContext: {}
}
})
};
fetch('https://api.velt.dev/v2/agents/execution/run', 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/run",
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>',
'url' => '<string>',
'crossPageExecute' => true,
'maxUrlsToProcess' => 123,
'deviceType' => '<string>',
'organizationId' => '<string>',
'documentId' => '<string>',
'trigger' => '<string>',
'workflowExecutionId' => '<string>',
'ranBy' => [
],
'userContext' => [
]
]
]),
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/run"
payload := strings.NewReader("{\n \"data\": {\n \"agentId\": \"<string>\",\n \"url\": \"<string>\",\n \"crossPageExecute\": true,\n \"maxUrlsToProcess\": 123,\n \"deviceType\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"trigger\": \"<string>\",\n \"workflowExecutionId\": \"<string>\",\n \"ranBy\": {},\n \"userContext\": {}\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/run")
.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 \"url\": \"<string>\",\n \"crossPageExecute\": true,\n \"maxUrlsToProcess\": 123,\n \"deviceType\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"trigger\": \"<string>\",\n \"workflowExecutionId\": \"<string>\",\n \"ranBy\": {},\n \"userContext\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/execution/run")
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 \"url\": \"<string>\",\n \"crossPageExecute\": true,\n \"maxUrlsToProcess\": 123,\n \"deviceType\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"trigger\": \"<string>\",\n \"workflowExecutionId\": \"<string>\",\n \"ranBy\": {},\n \"userContext\": {}\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Agent execution created successfully",
"data": {
"executionId": "exec_1711900000000_abc123def456"
}
}
}
Execution
Run Execution
POST
/
v2
/
agents
/
execution
/
run
Run Execution
curl --request POST \
--url https://api.velt.dev/v2/agents/execution/run \
--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>",
"url": "<string>",
"crossPageExecute": true,
"maxUrlsToProcess": 123,
"deviceType": "<string>",
"organizationId": "<string>",
"documentId": "<string>",
"trigger": "<string>",
"workflowExecutionId": "<string>",
"ranBy": {},
"userContext": {}
}
}
'import requests
url = "https://api.velt.dev/v2/agents/execution/run"
payload = { "data": {
"agentId": "<string>",
"url": "<string>",
"crossPageExecute": True,
"maxUrlsToProcess": 123,
"deviceType": "<string>",
"organizationId": "<string>",
"documentId": "<string>",
"trigger": "<string>",
"workflowExecutionId": "<string>",
"ranBy": {},
"userContext": {}
} }
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>',
url: '<string>',
crossPageExecute: true,
maxUrlsToProcess: 123,
deviceType: '<string>',
organizationId: '<string>',
documentId: '<string>',
trigger: '<string>',
workflowExecutionId: '<string>',
ranBy: {},
userContext: {}
}
})
};
fetch('https://api.velt.dev/v2/agents/execution/run', 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/run",
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>',
'url' => '<string>',
'crossPageExecute' => true,
'maxUrlsToProcess' => 123,
'deviceType' => '<string>',
'organizationId' => '<string>',
'documentId' => '<string>',
'trigger' => '<string>',
'workflowExecutionId' => '<string>',
'ranBy' => [
],
'userContext' => [
]
]
]),
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/run"
payload := strings.NewReader("{\n \"data\": {\n \"agentId\": \"<string>\",\n \"url\": \"<string>\",\n \"crossPageExecute\": true,\n \"maxUrlsToProcess\": 123,\n \"deviceType\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"trigger\": \"<string>\",\n \"workflowExecutionId\": \"<string>\",\n \"ranBy\": {},\n \"userContext\": {}\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/run")
.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 \"url\": \"<string>\",\n \"crossPageExecute\": true,\n \"maxUrlsToProcess\": 123,\n \"deviceType\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"trigger\": \"<string>\",\n \"workflowExecutionId\": \"<string>\",\n \"ranBy\": {},\n \"userContext\": {}\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/execution/run")
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 \"url\": \"<string>\",\n \"crossPageExecute\": true,\n \"maxUrlsToProcess\": 123,\n \"deviceType\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"trigger\": \"<string>\",\n \"workflowExecutionId\": \"<string>\",\n \"ranBy\": {},\n \"userContext\": {}\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Agent execution created successfully",
"data": {
"executionId": "exec_1711900000000_abc123def456"
}
}
}
Use this API to start an asynchronous agent execution. The engine creates an execution document in Firestore and dispatches a Cloud Task for processing. The response returns immediately with the
Errors:
executionId. Poll Get Execution to track progress and fetch findings.
The apiKey is injected from request headers. organizationId and documentId are required and identify the document the execution runs against — the document must already exist, and findings are persisted to it as comment annotations. Cross-page execution is controlled via the crossPageExecute boolean; there is no separate endpoint.
The schema uses .passthrough() so any additional fields are forwarded.
Endpoint
POST https://api.velt.dev/v2/agents/execution/run
Headers
Your API key.
Your Auth Token.
Body
Params
Show properties
Show properties
Min 1 char. Agent ID to execute.
Valid URL. The seed URL to process.
When true, the engine crawls the seed URL and processes up to
maxUrlsToProcess pages. Default: false.Max URLs to process when
crossPageExecute: true. Positive integer. Default: 50.Device mode to emulate for this execution:
"mobile" or "desktop". Default: "desktop". Drives the Puppeteer viewport/user-agent used by all context-gathering strategies and pin resolution, and sets pageInfo.deviceInfo.deviceType on every annotation the execution creates.Organization ID. Identifies the organization the execution runs against; findings are persisted to it as comment annotations.
Document ID. The document must already exist (unknown documents return
NOT_FOUND); findings are persisted to it as comment annotations."standalone" (default) or "workflow". Use "workflow" when running an agent as part of an Approval Engine workflow node.Parent workflow execution ID. Pair with
trigger: "workflow".User who triggered the execution.
| Field | Type | Required | Description |
|---|---|---|---|
userId | string | yes (if ranBy) | User ID |
name | string | no | Display name. Default: "". |
email | string | no | Email. Default: "". |
Runtime values for the agent’s
userContextFields. Keys must match the field IDs declared in the agent’s input.userContextFields.Example Requests
1. Single page execution
{
"data": {
"agentId": "abc123def456",
"url": "https://example.com/pricing",
"organizationId": "org_001",
"documentId": "doc_001",
"deviceType": "desktop",
"ranBy": {
"userId": "user_123",
"name": "Jane Doe",
"email": "jane@example.com"
}
}
}
2. Cross-page execution with user context (mobile)
{
"data": {
"agentId": "abc123def456",
"url": "https://example.com",
"crossPageExecute": true,
"maxUrlsToProcess": 25,
"deviceType": "mobile",
"organizationId": "org_001",
"documentId": "doc_001",
"trigger": "standalone",
"userContext": {
"brand_color": "#1A73E8",
"brand_font": "Inter",
"check_images": true
},
"ranBy": {
"userId": "user_123",
"name": "Jane Doe",
"email": "jane@example.com"
}
}
}
3. Workflow-triggered execution
{
"data": {
"agentId": "abc123def456",
"url": "https://example.com",
"trigger": "workflow",
"workflowExecutionId": "wf_exec_789",
"organizationId": "org_001",
"documentId": "doc_001",
"ranBy": { "userId": "user_123" }
}
}
4. Minimal request
{
"data": {
"agentId": "abc123def456",
"url": "https://example.com",
"organizationId": "org_001",
"documentId": "doc_001"
}
}
Response
Success Response
{
"result": {
"status": "success",
"message": "Agent execution created successfully",
"data": {
"executionId": "exec_1711900000000_abc123def456"
}
}
}
| Field | Type | Description |
|---|---|---|
data.executionId | string | Unique execution ID. Use to poll via Get Execution. |
Failure Response
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
INVALID_ARGUMENT (invalid URL; missing agentId, organizationId, or documentId; invalid trigger or deviceType) / NOT_FOUND (store database not found, or the target document does not exist) / ALREADY_EXISTS (an execution is already running for this agent + document combination; the error message includes the running execution’s ID) / RESOURCE_EXHAUSTED (the workspace’s AI credits are exhausted).
{
"result": {
"status": "success",
"message": "Agent execution created successfully",
"data": {
"executionId": "exec_1711900000000_abc123def456"
}
}
}
Was this page helpful?
⌘I

