Get Execution

POST /v2/agents/execution/get

Get Execution

cURL

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.status !== "running". Set includeResults: true to also fetch the per-URL findings subcollection.

Endpoint

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

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

executionId · string · required

Min 1 char. Execution ID returned from Run Execution.

includeResults · boolean

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": {
          "clientOrganizationId": "org_001",
          "clientDocumentId": "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": "[e-mail]" },
        "resultsSummary": {
          "totalFindings": 7,
          "totalAnnotationsCreated": 5,
          "urlsProcessed": 12,
          "urlsWithFindings": 5,
          "issuesCreated": 7,
          "summary": "Found 7 issues across 12 pages. 5 annotations created, 2 matched existing.",
          "matchResult": { "created": 5, "skipped": 2, "resolved": 1 }
        },
        "crawlerResults": { "status": "completed", "totalUrlsFound": 12, "duration": 45000, "pagesVisited": 12 },
        "llmModel": "claude/claude-sonnet-4-6",
        "tokenUsage": { "promptTokens": 12500, "completionTokens": 3200, "thoughtsTokens": 0, "totalTokens": 15700 }
      }
    }
  }
}

Execution document field reference:

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.clientOrganizationId	string	Client-provided organization ID.
metadata.clientDocumentId	string	Client-provided document ID.
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 (for match-and-merge reruns).
ranBy	object	{ userId, name, email } of who triggered.
resultsSummary.totalFindings	number	Total findings (after guardrails filtering).
resultsSummary.totalAnnotationsCreated	number	Annotations created (after match-and-merge dedup).
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	Match-and-merge outcome: { created, skipped, resolved }.
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
        }
      ]
    }
  }
}

Per-URL result fields:

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.

Finding fields (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	Match-and-merge key (e.g. "casing", "pii", "spelling", "broken-link").
confidence	number	0–100 confidence score. Below 50 may be suppressed by guardrails.
commentId	string	Comment annotation ID (populated after annotation creation).
source	string	"instructions" or "knowledge".

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "NOT_FOUND"
  }
}

Errors: 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
      }
    }
  }
}