> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Execution
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
Your API key.
Your [Auth Token](/docs/security/auth-tokens).
# Body
#### Params
Min 1 char. Execution ID returned from [Run Execution](/docs/api-reference/rest-apis/v2/agents/execution/run).
Include the full per-URL results subcollection. Default: `false`.
## **Example Requests**
#### 1. Poll status only
```JSON theme={null}
{
"data": {
"executionId": "exec_1711900000000_abc123def456"
}
}
```
#### 2. Fetch with full results
```JSON theme={null}
{
"data": {
"executionId": "exec_1711900000000_abc123def456",
"includeResults": true
}
}
```
# Response
#### Success Response (execution document)
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": {
"id": "exec_1711900000000_abc123def456",
"agentId": "abc123def456",
"agentName": "Brand Consistency Checker",
"agentVersion": 3,
"metadata": {
"organizationId": "org_001",
"documentId": "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": "jane@example.com" },
"resultsSummary": {
"totalFindings": 7,
"totalAnnotationsCreated": 7,
"urlsProcessed": 12,
"urlsWithFindings": 5,
"issuesCreated": 7,
"summary": "Found 7 issues across 12 pages. 7 annotations created."
},
"crawlerResults": { "status": "completed", "totalUrlsFound": 12, "duration": 45000, "pagesVisited": 12 },
"llmModel": "claude/claude-sonnet-5",
"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.organizationId` | string | The `organizationId` you passed on Run Execution. Empty string when absent. |
| `metadata.documentId` | string | The `documentId` you passed on Run Execution. Empty string when absent. |
| `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](/docs/ai/agents/overview#execution-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`, `CONTEXT_GATHERING_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 (set on reruns). |
| `ranBy` | object | `{ userId, name, email }` of who triggered. |
| `resultsSummary.totalFindings` | number | Total findings (after guardrails filtering). |
| `resultsSummary.totalAnnotationsCreated` | number | Annotations created. Re-runs first clear the prior run's suggestions per URL (delete-and-recreate), so this counts the fresh annotations written by this run. |
| `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.severityCounts` | object \| undefined | Finding counts keyed by severity, e.g. `{ "high": 2, "medium": 5, "low": 1 }`. Sparse: only severities with at least one finding are present, so treat a missing key as `0`. Possible keys are `critical`, `high`, `medium`, `low`, `info`. Absent entirely when the run produced no findings. |
| `resultsSummary.findings` | object\[] \| undefined | Sample of the run's findings for at-a-glance display, each `{ title, description, severity, sourceUrl?, issueType?, url? }`. Trimmed to the top 50 by severity once the execution reaches a terminal status; may exceed 50 while `status` is `"running"`. Absent when the run produced no findings. Use `includeResults: true` for the complete per-URL findings. |
| `resultsSummary.summary` | string \| null | Human-readable summary. Null while running. |
| `resultsSummary.matchResult` | object \| undefined | **Legacy.** Match-and-merge outcome (`{ created, skipped, resolved }`) written by the retired match-and-merge dedup. Present only on old execution documents; new executions use per-URL delete-and-recreate and never write this field. |
| `crawlerResults` | object \| undefined | Only populated when `crossPageExecute: true`. |
| `llmModel` | string \| undefined | LLM model used (e.g. `"claude/claude-sonnet-5"`, `"gemini/gemini-3.6-flash"`). |
| `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`:
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": "...same as above...",
"results": [
{
"id": "a1b2c3d4e5f6",
"url": "https://example.com",
"urlHash": "a1b2c3d4e5f6",
"agentId": "abc123def456",
"agentName": "Brand Guidelines Checker",
"agentResult": {
"status": "completed",
"summary": "Found 1 typography issue on the hero section.",
"issueCount": 1,
"findingsCount": 1,
"findings": [
{
"id": "finding-1",
"title": "Heading uses wrong font",
"description": "The h1 element uses 'Arial' instead of the brand font 'Inter'",
"severity": "high",
"targetText": "Welcome to Example",
"occurrence": 1,
"sourceUrl": "https://example.com",
"suggestion": "Change font-family to 'Inter' for the h1 element",
"htmlSelector": "h1.hero-title",
"targetElementXpath": "/html/body/main/section[1]/h1",
"isPageLevel": false,
"issueType": "brand-font",
"confidence": 92
}
]
},
"findingCount": 1,
"processedAt": 1711900050000
}
]
}
}
}
```
**Per-URL result fields:**
| Field | Type | Description |
| -------------- | ------ | ------------------------------------------------------------------------------------- |
| `id` | string | Result document ID. Same value as `urlHash`. |
| `url` | string | The URL that was analyzed. |
| `urlHash` | string | MD5 hash of the URL. |
| `agentId` | string | ID of the agent that produced this result. |
| `agentName` | string | Name of the agent at the time of the run. |
| `agentResult` | object | The agent's output for this URL. Findings live here, not at the top level. See below. |
| `findingCount` | number | Number of findings for this URL. Mirrors `agentResult.issueCount`. |
| `processedAt` | number | Epoch ms when this URL was processed. |
Findings are nested under `agentResult.findings`, not on the result row itself. Read `results[i].agentResult.findings`. Annotation counts are not reported per URL; use `resultsSummary.totalAnnotationsCreated` for the run-level total.
**Agent result fields (`agentResult`):**
| Field | Type | Description |
| --------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | string | `"completed"` or `"failed"` for this URL. |
| `agentId` | string | Duplicate of the row-level `agentId`. |
| `agentName` | string | Duplicate of the row-level `agentName`. |
| `summary` | string \| undefined | Run-level analysis summary, copied onto each URL row. Present only when the agent returned a flat findings list rather than a per-URL breakdown, so it is the same string for every URL in the run. |
| `issueCount` | number | Number of issues the agent raised for this URL. |
| `findingsCount` | number | Number of entries in `findings`. |
| `findings` | object\[] | Array of `AgentFinding` objects (see below). |
| `error` | string \| null | Failure message for this URL. `null` when the URL completed successfully. Always present, so test for failure with `status === "failed"`, not with the presence of this field. |
**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"`. |
| `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. |
| `targetElementXpath` | string | XPath of the DOM element. |
| `isPageLevel` | boolean | `true` for visual/layout findings; `false` when `targetText` matches DOM text. |
| `issueType` | string | Issue classification tag (e.g. `"casing"`, `"pii"`, `"spelling"`, `"broken-link"`). |
| `confidence` | number | 0–100 confidence score reported by the agent. |
| `commentId` | string | Comment annotation ID (populated after annotation creation). |
| `source` | string | `"instructions"` or `"knowledge"`. |
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "NOT_FOUND"
}
}
```
**Errors:** `NOT_FOUND` (`Execution not found: {executionId}` or `Store database not found`).
```js theme={null}
{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": {
"id": "exec_1711900000000_abc123def456",
"status": "running",
"startedAt": 1711900000000,
"completedAt": null,
"durationMs": null
}
}
}
}
```