---
title: "Start a behavioral-simulation audit of a URL"
method: POST
path: "/api/audits/run"
---

# Start a behavioral-simulation audit of a URL

`POST /api/audits/run`

## Request

- Base URL: `https://api.aetherya.ai`
- URL: `https://api.aetherya.ai/api/audits/run`
- Auth: HTTP bearer

Starts an async audit job. The job runs a synthetic audience against the target URL and produces predicted UX friction, hesitation, drop-off, and messaging-clarity findings. Poll `/api/audits/jobs/{jobId}` for status.

## Headers

- `X-Aetherya-Workspace-Id` string

## Request body

- object
  - `target` string, uri, required: The URL to audit.
  - `type` string[], required: Audit type(s). `["ux_ui"]` for a page audit, `["ux_journey"]` for a multi-step flow.
  - `cognitiveMode` boolean: Enable cognitive/behavioral persona simulation. Required to get persona-level findings.
  - `numAgents` integer: Number of synthetic personas to simulate.
  - `auditDepth` integer: How many pages to crawl.
  - `additionalInstructions` string: Plain-language focus or audience guidance for the simulation.
  - `personas` string[]: Optional list of persona ids to pin the simulation to.
  - `modelTier` string: Optional simulation quality tier.

## Response `200`

Audit job started successfully.

- object
  - `success` boolean, required
  - `jobId` string, required
  - `message` string

## Other responses

- `401`: Missing or invalid API key.
- `429`: Usage policy limit reached. The response identifies burst, weekly, monthly, concurrency, credits, or subscription_required and may include reset, upgrade, purchase, and workload-reduction guidance.

---

[API](https://skmtc.dev/aetherya/apis/aetherya-api.md) · [All operations](https://skmtc.dev/aetherya/apis/aetherya-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aetherya/apis/aetherya-api/revisions/afa076131ee1?raw)