---
title: "Trigger an asynchronous audit"
method: POST
path: "/v1/sites/{siteId}/audits"
tags: ["Sites"]
---

# Trigger an asynchronous audit

`POST /v1/sites/{siteId}/audits`

## Request

- Base URL: `https://api.ironfang.com/audit`
- URL: `https://api.ironfang.com/audit/v1/sites/{siteId}/audits`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Admits and queues an audit for the organisation's site and returns its initial lifecycle state. Admission comes first: the most pages the audit can capture (`page_bound`: the site's page limit within the per-audit cap, or one page for single_page) are reserved against the `audit.capture` meter of the organisation's billing account. A refusal is answered now with the shared billing code and no audit exists. The audit then captures at most `page_bound` pages and is charged only for the page evidence it finalises. Reusing an Idempotency-Key returns the existing audit and reserves nothing more; single_page limits the scope to the site's primary URL.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `reason` string
  - `single_page` boolean: Capture only the primary URL without following links or creating a monitor.
  - `trigger_type` string

## Response `200`

Idempotent replay; the existing audit

## Other responses

- `202`: Audit admitted and queued
- `402`: Problem response
- `403`: Problem response
- `404`: Problem response
- `410`: Problem response
- `413`: Problem response
- `429`: Problem response
- `503`: Problem response

---

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