# `run_audit`

Starts a full audit run for a brand. **Asynchronous** — returns immediately with a
`run_id` to poll.

**Tier:** mutate · **Rate limit:** 3 per 10 min (plus 3 per 10 min per target domain)

## Input

| Param | Type | Required | Default | Notes |
|---|---|---|---|---|
| `domain` | string | ✅ | — | Bare public hostname, e.g. `acme.com`. 3–253 chars. |
| `brand_name` | string | ✅ | — | 1–120 chars. As shoppers would refer to it. |
| `category` | string | ✅ | — | 1–120 chars, e.g. `trail running shoes`. |
| `competitors` | string[] | — | `[]` | Max 10 items, each 1–120 chars. |
| `refresh_profile` | boolean | — | unset | Re-read the site and discard the stored brand profile. |

### Domain validation

`domain` must be a bare hostname. Rejected: schemes, credentials, ports, paths, query
strings, fragments, whitespace, backslashes. It must contain a dot (so `localhost` is
rejected) and its final label must not be all-numeric (so `10.0.0.5` and
`169.254.169.254` are rejected). Each label is at most 63 characters.

These rules are an SSRF guard, not tidiness — the audit fetches this host.

!!!warning `refresh_profile` breaks comparability
Re-extracting the [brand profile](../../audit/brand-profile.md) changes the question set,
so the resulting score is **not comparable** with prior runs. Score deltas will report
`cross_query_set`. Use it when the brand genuinely changed what it sells, not to retry a
score you disliked.
!!!

`category` is used only for the [generic fallback question set](../../audit/query-generation.md#generic-questions-generic-v1)
and for grouping in [`compare_brands`](compare-brands.md). It never determines the
[archetype](../../concepts/brand-archetypes.md).

## Output

```json
{
  "run_id": "…",
  "brand_id": "…",
  "status": "pending",
  "message": "Audit started for Acme. Poll get_audit_status with this run_id."
}
```

`status` is always `pending` on return. The pipeline runs after the response is sent.

## Example

```json
{
  "domain": "brooklinen.com",
  "brand_name": "Brooklinen",
  "category": "bed sheets",
  "competitors": ["Parachute", "Boll & Branch"]
}
```

## Next

Poll [`get_audit_status`](get-audit-status.md). A run typically completes in a few
minutes — up to 20 engine calls plus judging.