---
title: "Start Seo Audit"
method: POST
path: "/seo/audits"
tags: ["SEO"]
---

# Start Seo Audit

`POST /seo/audits`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/seo/audits`
- Auth: HTTP bearer

SPENDS CREDITS. Start a site audit of up to `max_pages` pages.

Credits are RESERVED up front, sized by `max_pages`, and charged as the
crawl completes - `credits_charged` on the audit says what was. 402 when
the balance cannot cover the reservation, 409 when an audit of this domain
is already running, 503 when the credit service cannot take the hold.

The audit runs in the background; poll `GET /seo/audits/{audit_id}` and
read `state`, which explains where it is in plain language and whether it
can be run again.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- SeoStartAuditRequest: Mirrors `StartAuditRequest`. `max_pages` is the crawl ceiling and the thing the credit reservation is sized from.
  - `domain` string, required
  - `max_pages` integer
  - `allow_subdomains` boolean
  - `enable_javascript` boolean

## Response `200`

Successful Response

- ApiResponseSeoAudit
  - `data` SeoAudit, required: Mirrors `AuditDTO`.
    - `id` string, uuid, required
    - `domain` string, required
    - `status` string, required
    - `max_pages` integer, required
    - `pages_crawled` integer, nullable
    - `credits_charged` integer, nullable
    - `onpage_score` number, nullable
    - `summary_checks` object
    - `failure_reason` string, nullable
    - `enable_javascript` boolean
    - `state` SeoAuditState, required: Mirrors `AuditStateDTO` - the plain-language, recovery-oriented view of where an audit is, so a caller can explain the state rather than parse raw provider text.
      - `category` 'queued' | 'running' | 'complete' | 'timeout' | 'provider_error' | 'credit_issue' | 'start_error' | 'failed', required: Lifecycle state category driving the plain-language status + recovery UX
      - `label` string, required: Short status chip label
      - `headline` string, required: One-line human status
      - `detail` string, required: Plain-language explanation of what happened
      - `recovery` string, required: Plain-language, safe next step (may be empty)
      - `can_run_again` boolean, required: Whether to offer a manual 'Run a new audit' action
      - `is_terminal` boolean, required: No further automatic progress will happen
      - `diagnostic` string, nullable: Secondary technical detail (raw provider text)
    - `created_at` string, date-time, nullable
    - `completed_at` string, date-time, nullable
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

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