Skip to main content
POST
Run Execution
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

Body

Params

data
object
required

Example Requests

1. Single page execution

2. Cross-page execution with user context

3. Workflow-triggered execution

4. Minimal request

Response

Success Response

FieldTypeDescription
data.executionIdstringUnique execution ID. Use to poll via Get Execution.

Failure Response

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).