> ## Documentation Index
> Fetch the complete documentation index at: https://velt-raghul-agent-docs.mintlify.site/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 — call it after [Run Execution](/api-reference/rest-apis/v2/agents/execution/run) 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
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Min 1 char. Execution ID returned from [Run Execution](/api-reference/rest-apis/v2/agents/execution/run).
Include the full per-URL findings 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
```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": {
"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`)
```JSON theme={null}
{
"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
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "NOT_FOUND"
}
}
```
**Errors:** `NOT_FOUND` (execution or store database not found) / `INVALID_ARGUMENT` (missing or empty `executionId`).
```js theme={null}
{
"result": {
"status": "success",
"message": "Execution fetched successfully",
"data": {
"execution": {
"id": "exec_1711900000000_abc123def456",
"status": "running",
"startedAt": 1711900000000,
"completedAt": null,
"durationMs": null
}
}
}
}
```