Run Execution

POST /v2/agents/execution/run

Run Execution

cURL

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,
    "organizationId": "<string>",
    "documentId": "<string>",
    "trigger": "<string>",
    "workflowExecutionId": "<string>",
    "ranBy": {},
    "userContext": {}
  }
}
'

{
  "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 executionId — poll Get Execution to track progress and fetch findings.

The apiKey is injected from request headers. Pass organizationId and documentId at the top level of the body if you want findings to land as comment annotations on a specific document. Cross-page execution is controlled via the crossPageExecute boolean — no separate endpoint.

The schema uses .passthrough() so any additional fields are forwarded.

Endpoint

POST https://api.velt.dev/v2/agents/execution/run

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

agentId · string · required

Min 1 char. Agent ID to execute.

url · string · required

Valid URL. The seed URL to process.

crossPageExecute · boolean

When true, the engine crawls the seed URL and processes up to maxUrlsToProcess pages. Default: false.

maxUrlsToProcess · number

Max URLs to process when crossPageExecute: true. Positive integer. Default: 50.

organizationId · string

Client organization ID. Required for findings to be persisted as comment annotations.

documentId · string

Client document ID. Required for findings to be persisted as comment annotations.

trigger · string

"standalone" (default) or "workflow". Use "workflow" when running an agent as part of an Approval Engine workflow node.

workflowExecutionId · string

Parent workflow execution ID. Pair with trigger: "workflow".

ranBy · object

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: "".

userContext · object

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",
    "ranBy": {
      "userId": "user_123",
      "name": "Jane Doe",
      "email": "[e-mail]"
    }
  }
}

2. Cross-page execution with user context

{
  "data": {
    "agentId": "abc123def456",
    "url": "https://example.com",
    "crossPageExecute": true,
    "maxUrlsToProcess": 25,
    "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": "[e-mail]"
    }
  }
}

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

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

Errors: INVALID_ARGUMENT (invalid URL, missing required fields, invalid trigger) / NOT_FOUND (agent does not exist) / FAILED_PRECONDITION (agent is disabled, store database not found, or active execution already exists for this document).

{
  "result": {
    "status": "success",
    "message": "Agent execution created successfully",
    "data": {
      "executionId": "exec_1711900000000_abc123def456"
    }
  }
}