Audit Methods

The SDK provides methods to create audits and retrieve results.

audits.create()

Submit a URL for UX and accessibility analysis. Returns immediately with a job ID for polling.

Signature

client.audits.create(params: AuditRequest): Promise<AuditCreatedResponse>

Parameters

Parameter	Type	Required	Description
url	`string`	required	Website URL to audit (http or https)
mode	`'basic' \| 'standard' \| 'deep'`	optional	Audit depth. Default: 'basic'
metadata	`Record<string, unknown>`	optional	Custom key-value data to attach to the audit

Audit Modes

Mode	Duration	Description
`basic`	~30s	Core accessibility and UX checks
`standard`	~2min	Full WCAG 2.1 AA analysis
`deep`	~5min	Multi-page crawl with performance metrics

Response

type

properties

Example

import { VertaaUX } from '@vertaaux/sdk';

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
});

try {
  const job = await client.audits.create({
    url: 'https://example.com',
    mode: 'standard',
    metadata: {
      project: 'ecommerce-redesign',
      environment: 'staging',
    },
  });

  console.log('Audit started:', job.job_id);
  console.log('Status:', job.status); // "queued"
} catch (error) {
  console.error('Failed to create audit:', error);
}

audits.get()

Retrieve the status and results of an audit job.

Signature

client.audits.get(jobId: string): Promise<AuditStatusResponse>

Parameters

Parameter	Type	Required	Description
jobId	`string`	required	Job ID returned from audits.create()

Status Values

Status	Description
`queued`	Waiting for worker
`running`	Analysis in progress
`completed`	Results available
`failed`	Error occurred (see `error` field)

Response

type

properties

Basic Example

const result = await client.audits.get('clu1a2b3c4d5e6f7g8h9i0j1');

console.log('Status:', result.status);
console.log('Progress:', result.progress + '%');

if (result.status === 'completed') {
  console.log('Overall score:', result.scores?.overall);
  console.log('Issues found:', result.issues?.length);
}

Polling Pattern

Since audits run asynchronously, poll the status until completion:

Recommended Polling Approach

import { VertaaUX } from '@vertaaux/sdk';

async function waitForAudit(
  client: VertaaUX,
  jobId: string,
  options?: { pollInterval?: number; timeout?: number }
) {
  const pollInterval = options?.pollInterval ?? 2000; // 2 seconds
  const timeout = options?.timeout ?? 600000; // 10 minutes
  const startTime = Date.now();

  while (true) {
    const result = await client.audits.get(jobId);

    // Return completed or failed results
    if (result.status === 'completed' || result.status === 'failed') {
      return result;
    }

    // Check timeout
    if (Date.now() - startTime > timeout) {
      throw new Error(`Audit timed out after ${timeout}ms`);
    }

    // Wait before next poll
    await new Promise((r) => setTimeout(r, pollInterval));
  }
}

Usage with Polling Helper

const client = new VertaaUX({
  apiKey: process.env.VERTAA_API_KEY!,
});

// Start audit
const job = await client.audits.create({
  url: 'https://example.com',
  mode: 'standard',
});

// Wait for completion
const result = await waitForAudit(client, job.job_id, {
  pollInterval: 3000, // 3 seconds between polls
  timeout: 300000,    // 5 minute timeout
});

if (result.status === 'completed') {
  console.log('Score:', result.scores?.overall);
} else {
  console.error('Audit failed:', result.error);
}

Backoff Recommendations

For production systems:

Audit Mode	Recommended Poll Interval
`basic`	2 seconds
`standard`	3 seconds
`deep`	5 seconds

For production applications, use webhooks instead of polling to receive notifications when audits complete.

Complete Workflow Example

Full example combining create and poll:

run-audit.ts

import { VertaaUX } from '@vertaaux/sdk';

async function runAudit(url: string) {
  const client = new VertaaUX({
    apiKey: process.env.VERTAA_API_KEY!,
  });

  // 1. Create audit
  console.log(`Starting audit for ${url}...`);
  const job = await client.audits.create({
    url,
    mode: 'standard',
    metadata: {
      source: 'sdk-example',
      timestamp: new Date().toISOString(),
    },
  });
  console.log(`Job ID: ${job.job_id}`);

  // 2. Poll for completion
  let result;
  const startTime = Date.now();
  do {
    result = await client.audits.get(job.job_id);
    const elapsed = ((Date.now() - startTime) / 1000).toFixed(0);
    console.log(`[${elapsed}s] Status: ${result.status}, Progress: ${result.progress}%`);

    if (result.status === 'queued' || result.status === 'running') {
      await new Promise((r) => setTimeout(r, 3000));
    }
  } while (result.status === 'queued' || result.status === 'running');

  // 3. Handle results
  if (result.status === 'completed') {
    console.log('\n=== Audit Results ===');
    console.log(`Overall Score: ${result.scores?.overall}/100`);
    console.log(`UX Score: ${result.scores?.ux}/100`);
    console.log(`Accessibility Score: ${result.scores?.accessibility}/100`);
    console.log(`\nIssues Found: ${result.issues?.length || 0}`);

    // Group by severity
    const errors = result.issues?.filter((i) => i.severity === 'error') || [];
    const warnings = result.issues?.filter((i) => i.severity === 'warning') || [];
    const info = result.issues?.filter((i) => i.severity === 'info') || [];

    console.log(`  - Errors: ${errors.length}`);
    console.log(`  - Warnings: ${warnings.length}`);
    console.log(`  - Info: ${info.length}`);

    // Show top errors
    if (errors.length > 0) {
      console.log('\nTop Errors:');
      errors.slice(0, 3).forEach((issue, i) => {
        console.log(`${i + 1}. ${issue.description}`);
        console.log(`   Fix: ${issue.recommendation}`);
      });
    }

    return result;
  } else {
    throw new Error(`Audit failed: ${result.error}`);
  }
}

// Run it
runAudit('https://example.com').catch(console.error);

Also Available

The same audit functionality is available through:

REST API - POST /v1/audit
CLI - vertaa audit --url https://example.com

Webhook Methods - Get notified when audits complete
Error Handling - Handle rate limits and failures
TypeScript Types - AuditRequest and AuditStatusResponse types

Was this page helpful?

Audit Methods

On this page