audit_url

Audit a deployed website URL for UX and accessibility issues. This is the primary entry point for most auditing workflows.

Description

The audit_url tool runs a comprehensive UX and accessibility audit on any publicly accessible URL. It captures screenshots, analyzes the page, and returns findings with severity ratings.

Parameters

Parameter	Type	Required	Description
url	`string`	required	Website URL to audit (must be publicly accessible or localhost)
mode	`'basic' \| 'standard' \| 'deep'`	optional	Audit depth. Default: 'standard'
timeout_ms	`number`	optional	Maximum time to wait for audit completion. Max: 120000, Default: 60000
wait	`boolean`	optional	Wait for audit completion before returning. Default: true
baseline_id	`string`	optional	Previous audit ID for change tracking (diff mode)
offline	`boolean`	optional	Enable for local HTML files or Storybook. Default: false

Audit Modes

Mode	Duration	Checks	Best For
`basic`	~30s	Core accessibility (WCAG A)	Quick verification, CI gates
`standard`	~2min	Full WCAG 2.1 AA + UX heuristics	Regular audits, PR checks
`deep`	~5min	Multi-page crawl, performance, AA+AAA	Comprehensive reviews, compliance

Response

type

properties

Example Conversations

Basic Audit

"Audit https://mysite.com"

Claude runs audit_url with default settings:

audit_url({
  url: "https://mysite.com"
})

Deep Audit with Extended Timeout

"Do a deep audit of https://staging.mysite.com with a 2 minute timeout"

Claude uses explicit parameters:

audit_url({
  url: "https://staging.mysite.com",
  mode: "deep",
  timeout_ms: 120000
})

Local Development Audit

"Audit my local Storybook at http://localhost:6006"

Claude enables offline mode for localhost:

audit_url({
  url: "http://localhost:6006",
  offline: true
})

Comparison with Baseline

"Audit the homepage and compare it to last week's baseline audit"

Claude uses the baseline_id parameter:

audit_url({
  url: "https://mysite.com",
  baseline_id: "aud_previous_123"
})

Response includes a changes section showing new, fixed, and unchanged findings.

Error Handling

Error	Cause	Solution
`INVALID_URL`	URL is malformed or not accessible	Check URL format and ensure it's publicly reachable
`TIMEOUT`	Audit exceeded timeout_ms	Increase timeout or use `basic` mode
`UNAUTHORIZED`	Invalid API key	Check API key configuration
`QUOTA_EXCEEDED`	Monthly audit limit reached	Upgrade plan or wait for reset
`NETWORK_ERROR`	Cannot reach the target URL	Verify URL is accessible and not blocking requests

Tips

Choosing the Right Mode

CI/CD pipelines: Use basic for fast feedback
PR reviews: Use standard for balanced coverage
Compliance audits: Use deep for thorough analysis

Using with Localhost

For local development servers:

Ensure your dev server is running
Use offline: true for local files
Works with: webpack-dev-server, Vite, Storybook, etc.

Baseline Comparisons

To track changes over time:

Save the audit_id from your first audit
Use it as baseline_id in subsequent audits
The response will include a diff showing new/fixed issues

get_findings - Retrieve detailed findings
suggest_fix - Get AI-suggested fixes
API: Create Audit - REST API equivalent

Was this page helpful?

audit_url

On this page