Use this API to fetch an execution document by ID. This is the polling endpoint — call it after Run Execution and 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 findings 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

{
  "result": {
    "status": "success",
    "message": "Execution fetched successfully",
    "data": {
      "execution": {
        "id": "exec_1711900000000_abc123def456",
        "agentId": "abc123def456",
        "agentName": "Brand Consistency Checker",
        "agentVersion": 3,
        "metadata": {
          "apiKey": "ak_xxx",
          "organizationId": "server_org_001",
          "clientOrganizationId": "org_001",
          "documentId": "server_doc_001",
          "clientDocumentId": "doc_001"
        },
        "config": {
          "seedUrl": "https://example.com",
          "crossPageExecute": true,
          "maxUrlsToProcess": 25,
          "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": 5,
          "urlsProcessed": 12,
          "urlsWithFindings": 5,
          "issuesCreated": 7,
          "summary": "Found 7 issues across 12 pages. 5 annotations created, 2 matched existing annotations.",
          "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
        },
        "knowledgeRetrieved": true,
        "knowledgeCached": false,
        "degraded": false
      }
    }
  }
}

Execution document fields

Field	Type	Description
`id`	string	Execution ID
`agentId`	string	Agent that was executed
`agentName`	string	Denormalized agent display name
`agentVersion`	number	Agent config version pinned at dispatch time
`metadata.apiKey`	string	Workspace API key
`metadata.organizationId`	string	Server-namespaced organization ID
`metadata.clientOrganizationId`	string	Client-provided organization ID
`metadata.documentId`	string	Server-namespaced document 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.crawlerConfig`	object \| undefined	Crawler config (only when `crossPageExecute: true`)
`status`	string	`"running"`, `"passed"`, `"failed"`, `"error"`, `"skipped"`
`startedAt`	number	Epoch ms
`completedAt`	number \| null	Epoch ms when completed; null while running
`durationMs`	number \| null	Total duration in ms
`error`	object \| undefined	Populated on `error` or `failed` status
`error.code`	string	One of `TIMEOUT`, `LLM_ERROR`, `LLM_RATE_LIMITED`, `MALFORMED_RESPONSE`, `CRAWLER_ERROR`, `EXTRACTION_ERROR`, `POST_PROCESS_ERROR`, `INTERNAL`
`error.message`	string	Human-readable error description
`error.retryable`	boolean	Whether this error can be retried
`error.advisoryComment`	string \| undefined	Advisory comment text posted to the document
`error.occurredAt`	number	Epoch ms
`trigger`	string	`"standalone"` or `"workflow"`
`workflowExecutionId`	string \| undefined	Parent workflow execution ID (workflow-triggered runs)
`previousExecutionId`	string \| undefined	Previous execution ID (for match-and-merge reruns)
`ranBy.userId`	string	User ID
`ranBy.name`	string	Display name
`ranBy.email`	string	Email
`resultsSummary.totalFindings`	number	Total findings (after guardrails filtering)
`resultsSummary.totalAnnotationsCreated`	number	Annotations created (after match-and-merge dedup)
`resultsSummary.urlsProcessed`	number	URLs processed
`resultsSummary.urlsWithFindings`	number	URLs that had at least one finding
`resultsSummary.matchResult`	object \| undefined	`{ created, skipped, resolved }` — match-and-merge outcome
`crawlerResults`	object \| undefined	Only populated when `crossPageExecute: true`
`llmModel`	string \| undefined	LLM model used (e.g. `"claude/claude-sonnet-4-6"`)
`tokenUsage`	object	`{ promptTokens, completionTokens, thoughtsTokens, totalTokens }`
`knowledgeRetrieved`	boolean \| undefined	Whether knowledge was retrieved from Memory
`knowledgeCached`	boolean \| undefined	Whether knowledge retrieval was served from cache
`degraded`	boolean \| undefined	Whether the agent ran in degraded mode

Success Response (with results — `includeResults: true`)

{
  "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 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 analyzed
`urlHash`	string	MD5 hash of the URL (Firestore doc ID)
`findings`	object[]	Array of `AgentFinding` objects
`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	Required	Description
`id`	string	yes	Unique finding ID (e.g. `"finding-1"`)
`title`	string	yes	Short title
`description`	string	yes	Detailed description
`severity`	string	yes	`critical`, `high`, `medium`, `low`, `info`
`category`	string	no	Grouping tag (e.g. `accessibility`, `seo`, `content`, `layout`)
`targetText`	string	yes	Exact DOM text. Empty string for image/non-text findings
`occurrence`	number	no	1-based occurrence index of `targetText` on the page
`sourceUrl`	string	no	URL where the finding was detected
`suggestion`	string	no	Suggested fix
`htmlSelector`	string	yes	CSS selector of the DOM element
`htmlXpath`	string	yes	XPath of the DOM element
`htmlSnippet`	string	no	Surrounding HTML snippet for context
`isPageLevel`	boolean	yes	`true` for visual/layout findings; `false` when targetText matches DOM text
`issueType`	string	no	Match-and-merge key (e.g. `"casing"`, `"pii"`, `"spelling"`)
`confidence`	number	no	0-100. Findings below 50 may be suppressed by guardrails
`commentId`	string	no	Comment annotation ID populated after annotation creation
`source`	string	no	`"instructions"` or `"knowledge"`
`metadata`	object	no	Additional finding-specific metadata

Failure Response

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

Errors: NOT_FOUND (execution or store database not found) / INVALID_ARGUMENT (missing or empty executionId).

{
  "result": {
    "status": "success",
    "message": "Execution fetched successfully",
    "data": {
      "execution": {
        "id": "exec_1711900000000_abc123def456",
        "status": "running",
        "startedAt": 1711900000000,
        "completedAt": null,
        "durationMs": null
      }
    }
  }
}

REST APIs

SDK

Get Execution

Endpoint

Headers

Body

Params

Example Requests

1. Poll status only

2. Fetch with full results

Response

Success Response

Execution document fields

Success Response (with results — `includeResults: true`)

Per-URL result fields

Finding fields (`AgentFinding`)

Failure Response

REST APIs

SDK

Documentation Index

​Endpoint

​Headers

​Body

​Params

​Example Requests

​1. Poll status only

​2. Fetch with full results

​Response

​Success Response

​Execution document fields

​Success Response (with results — includeResults: true)

​Per-URL result fields

​Finding fields (AgentFinding)

​Failure Response

Endpoint

Headers

Body

Params

Example Requests

1. Poll status only

2. Fetch with full results

Response

Success Response

Execution document fields

Success Response (with results — `includeResults: true`)

Per-URL result fields

Finding fields (`AgentFinding`)

Failure Response