Skip to main content
VertaaUX Docs
APIEndpoints

Get Audit

Check audit status and retrieve results

Get Audit

GET/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

ParameterTypeRequiredDescription
job_idstringrequiredThe unique identifier returned when the audit was created.

Query Parameters

ParameterTypeRequiredDescription
severitystringoptionalFilter issues by severity level.
errorenumoptionalCritical issues that must be fixed.
warningenumoptionalImportant issues that should be addressed.
infoenumoptionalSuggestions for improvement.
fieldsstringoptionalComma-separated list of issue fields to include (e.g., 'id,severity,message'). Reduces response size.
pagenumberoptionalPage number for paginated issues.Default: 1
per_pagenumberoptionalNumber of issues per page (max 1000).Default: 100
deltabooleanoptionalInclude score comparison with previous audit of the same URL.Default: false

Response

Pending/Running Audit

job_idstring

Unique identifier for the audit job.

statusstringenum: queued | running

Current job status.

urlstring

The URL being audited.

modestring

The audit mode.

progressnumber

Progress percentage (0-100).

created_atstring

ISO 8601 timestamp when the job was created.

started_atstring

ISO 8601 timestamp when processing started (if running).

ruleset_versionstring

Version of the UX ruleset being applied.

Completed Audit

job_idstring

Unique identifier for the audit job.

statusstringenum: completed

Job status.

urlstring

The URL audited.

modestring

The audit mode used.

progressnumber

Always 100 for completed audits.

created_atstring

ISO 8601 timestamp when the job was created.

started_atstring

ISO 8601 timestamp when processing started.

completed_atstring

ISO 8601 timestamp when the audit finished.

scoresobject

Category scores (0-100).

issuesarray

List of issues found.

total_issuesnumber

Total number of issues (before pagination).

total_pagesnumber

Total number of pages for pagination.

pagenumber

Current page number.

per_pagenumber

Issues per page.

ruleset_versionstring

Version of the UX ruleset applied.

engine_versionstring

Version of the audit engine used.

metadataobject

Additional audit metadata.

deltaobject

Score 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

StatusDescription
200 OKAudit found. Check status field for completion state.
401 UnauthorizedMissing or invalid API key.
403 ForbiddenYou don't have access to this audit (belongs to another user).
404 Not FoundAudit 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
done
import 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=3600 for completed audits
  • Cache-Control: no-cache, no-store for pending/running/failed audits

Also Available

InterfaceCommand/Method
CLIvertaa audit --wait https://example.com
SDKclient.audits.get(jobId)

Was this page helpful?

On this page