Get Audit
Check audit status and retrieve results
Get Audit
/v1/audit/{job_id}Retrieve the status and results of an audit job. Poll this endpoint until the status is completed or failed.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| job_id | string | required | The unique identifier returned when the audit was created. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| severity | string | optional | Filter issues by severity level. |
| ↳error | enum | optional | Critical issues that must be fixed. |
| ↳warning | enum | optional | Important issues that should be addressed. |
| ↳info | enum | optional | Suggestions for improvement. |
| fields | string | optional | Comma-separated list of issue fields to include (e.g., 'id,severity,message'). Reduces response size. |
| page | number | optional | Page number for paginated issues.Default: 1 |
| per_page | number | optional | Number of issues per page (max 1000).Default: 100 |
| delta | boolean | optional | Include score comparison with previous audit of the same URL.Default: false |
Response
Pending/Running Audit
job_idstringUnique identifier for the audit job.
statusstringenum: queued | runningCurrent job status.
urlstringThe URL being audited.
modestringThe audit mode.
progressnumberProgress percentage (0-100).
created_atstringISO 8601 timestamp when the job was created.
started_atstringISO 8601 timestamp when processing started (if running).
ruleset_versionstringVersion of the UX ruleset being applied.
Completed Audit
job_idstringUnique identifier for the audit job.
statusstringenum: completedJob status.
urlstringThe URL audited.
modestringThe audit mode used.
progressnumberAlways 100 for completed audits.
created_atstringISO 8601 timestamp when the job was created.
started_atstringISO 8601 timestamp when processing started.
completed_atstringISO 8601 timestamp when the audit finished.
scoresobjectCategory scores (0-100).
issuesarrayList of issues found.
total_issuesnumberTotal number of issues (before pagination).
total_pagesnumberTotal number of pages for pagination.
pagenumberCurrent page number.
per_pagenumberIssues per page.
ruleset_versionstringVersion of the UX ruleset applied.
engine_versionstringVersion of the audit engine used.
metadataobjectAdditional audit metadata.
deltaobjectScore comparison with previous audit (if delta=true).
Example Response (Completed)
{
"job_id": "clu1a2b3c4d5e6f7g8h9i0j1",
"status": "completed",
"url": "https://example.com",
"mode": "standard",
"progress": 100,
"created_at": "2024-01-15T10:30:00Z",
"started_at": "2024-01-15T10:30:05Z",
"completed_at": "2024-01-15T10:31:15Z",
"scores": {
"overall": 85,
"ux": 88,
"accessibility": 82,
"information_architecture": 86,
"performance": 84
},
"issues": [
{
"id": "issue_1",
"severity": "warning",
"category": "accessibility",
"rule": "color-contrast",
"message": "Text has insufficient color contrast (3.2:1, minimum 4.5:1)",
"selector": "#hero-subtitle",
"wcag": "1.4.3"
},
{
"id": "issue_2",
"severity": "error",
"category": "ux",
"rule": "touch-target-size",
"message": "Touch target is too small (32x32px, minimum 44x44px)",
"selector": ".mobile-nav-toggle"
}
],
"total_issues": 2,
"total_pages": 1,
"page": 1,
"per_page": 100,
"ruleset_version": "2024.1",
"engine_version": "latest",
"metadata": {
"heatmap_url": "https://cdn.vertaaux.ai/heatmaps/abc123-def456.png",
"heatmap_model_version": "heatmap-student-v0"
}
}Failed Audit
{
"job_id": "clu1a2b3c4d5e6f7g8h9i0j1",
"status": "failed",
"url": "https://example.com",
"mode": "standard",
"progress": 15,
"created_at": "2024-01-15T10:30:00Z",
"started_at": "2024-01-15T10:30:05Z",
"error": "Page timed out after 30000ms",
"ruleset_version": "2024.1"
}HTTP Status Codes
| Status | Description |
|---|---|
200 OK | Audit found. Check status field for completion state. |
401 Unauthorized | Missing or invalid API key. |
403 Forbidden | You don't have access to this audit (belongs to another user). |
404 Not Found | Audit job not found. |
Code Examples
Polling for Results
import 'dotenv/config';
interface AuditResult {
job_id: string;
status: 'queued' | 'running' | 'completed' | 'failed';
url: string;
progress: number;
scores?: {
overall: number;
ux: number;
accessibility: number;
information_architecture: number;
performance: number;
};
issues?: Array<{
id: string;
severity: 'error' | 'warning' | 'info';
category: string;
rule: string;
message: string;
selector?: string;
wcag?: string;
}>;
total_issues?: number;
error?: string;
}
async function pollAudit(
jobId: string,
intervalMs = 2000,
maxAttempts = 60
): Promise<AuditResult> {
const apiKey = process.env.VERTAAUX_API_KEY!;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const response = await fetch(
`https://vertaaux.ai/api/v1/audit/${jobId}`,
{
headers: { 'X-API-Key': apiKey },
}
);
if (!response.ok) {
const error = await response.json();
throw new Error(`Failed to get audit: ${error.message}`);
}
const result: AuditResult = await response.json();
if (result.status === 'completed') {
return result;
}
if (result.status === 'failed') {
throw new Error(`Audit failed: ${result.error}`);
}
console.log(`Progress: ${result.progress}%`);
// Exponential backoff: increase interval after 10 attempts
const delay = attempt > 10 ? intervalMs * 2 : intervalMs;
await new Promise((resolve) => setTimeout(resolve, delay));
}
throw new Error('Audit timed out');
}
// Usage
const result = await pollAudit('clu1a2b3c4d5e6f7g8h9i0j1');
console.log(`Overall score: ${result.scores?.overall}`);
console.log(`Issues found: ${result.total_issues}`);#!/bin/bash
JOB_ID="clu1a2b3c4d5e6f7g8h9i0j1"
while true; do
RESULT=$(curl -s "https://vertaaux.ai/api/v1/audit/$JOB_ID" \
-H "X-API-Key: $VERTAAUX_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.status')
PROGRESS=$(echo "$RESULT" | jq -r '.progress')
if [ "$STATUS" = "completed" ]; then
echo "Audit complete!"
echo "$RESULT" | jq '{scores, total_issues}'
break
elif [ "$STATUS" = "failed" ]; then
echo "Audit failed: $(echo "$RESULT" | jq -r '.error')"
exit 1
fi
echo "Progress: $PROGRESS%"
sleep 2
doneimport os
import time
import requests
from typing import TypedDict, Literal, Optional
class Scores(TypedDict):
overall: int
ux: int
accessibility: int
information_architecture: int
performance: int
class Issue(TypedDict):
id: str
severity: Literal['error', 'warning', 'info']
category: str
rule: str
message: str
selector: Optional[str]
wcag: Optional[str]
class AuditResult(TypedDict):
job_id: str
status: Literal['queued', 'running', 'completed', 'failed']
url: str
progress: int
scores: Optional[Scores]
issues: Optional[list[Issue]]
total_issues: Optional[int]
error: Optional[str]
def poll_audit(
job_id: str,
interval_seconds: float = 2.0,
max_attempts: int = 60
) -> AuditResult:
"""Poll for audit results with exponential backoff."""
api_key = os.environ['VERTAAUX_API_KEY']
for attempt in range(max_attempts):
response = requests.get(
f'https://vertaaux.ai/api/v1/audit/{job_id}',
headers={'X-API-Key': api_key}
)
if not response.ok:
error = response.json()
raise Exception(f"Failed to get audit: {error.get('message')}")
result: AuditResult = response.json()
if result['status'] == 'completed':
return result
if result['status'] == 'failed':
raise Exception(f"Audit failed: {result.get('error')}")
print(f"Progress: {result['progress']}%")
# Exponential backoff after 10 attempts
delay = interval_seconds * 2 if attempt > 10 else interval_seconds
time.sleep(delay)
raise Exception('Audit timed out')
# Usage
result = poll_audit('clu1a2b3c4d5e6f7g8h9i0j1')
print(f"Overall score: {result['scores']['overall']}")
print(f"Issues found: {result['total_issues']}")With Delta Comparison
# Include comparison with previous audit
curl "https://vertaaux.ai/api/v1/audit/clu1a2b3c4d5e6f7g8h9i0j1?delta=true" \
-H "X-API-Key: $VERTAAUX_API_KEY"Response with delta:
{
"job_id": "clu1a2b3c4d5e6f7g8h9i0j1",
"status": "completed",
"scores": {
"overall": 85,
"ux": 88,
"accessibility": 82
},
"delta": {
"overall": 3,
"categories": {
"ux": 2,
"accessibility": 5,
"information_architecture": 1,
"performance": 4
},
"previous_job_id": "clu0xyz789",
"previous_completed_at": "2024-01-14T10:30:00Z"
}
}Filtering Issues
# Only errors
curl "https://vertaaux.ai/api/v1/audit/$JOB_ID?severity=error" \
-H "X-API-Key: $VERTAAUX_API_KEY"
# Select specific fields
curl "https://vertaaux.ai/api/v1/audit/$JOB_ID?fields=id,severity,message" \
-H "X-API-Key: $VERTAAUX_API_KEY"
# Paginate large result sets
curl "https://vertaaux.ai/api/v1/audit/$JOB_ID?page=2&per_page=50" \
-H "X-API-Key: $VERTAAUX_API_KEY"Caching
Completed audits are cached for 1 hour (immutable results). In-progress audits are not cached.
Cache-Control: public, max-age=3600for completed auditsCache-Control: no-cache, no-storefor pending/running/failed audits
Also Available
Related
Stream Issues
Stream issues in real-time with NDJSON
Webhooks
Get notified instead of polling
Error Handling
Handle errors gracefully
Was this page helpful?