Audit statuses and failure reasons

An audit moves from queued to running to finalizing to done. It can also end as failed (with a failure_reason) or cancelled. Whatever the outcome, you pay only for pages actually crawled: the rest of the reserved credits returns to your balance within about a minute of the audit ending.

#Statuses

In the app, the audit page shows "Queued", "Crawling", "Building report" and "Done" while it runs, and "This audit failed" or "Audit cancelled" when it stops, with the pages crawled and the failure reason.

Agents: get_audit_status (MCP) or GET /v1/crawls/{id}:

{
  "crawl_id": 1843,
  "status": "failed",
  "pages_crawled": 1210,
  "max_pages": 2000,
  "credits_reserved": 2000,
  "failure_reason": "reaped: stalled",
  "max_rps": 2,
  "duration_s": 1020
}

#failure_reason values

The app words these as: "The crawler stopped reporting progress, so the audit was stopped." (reaped), "We couldn't hand the audit to a crawler." (dispatch_failed), "The audit couldn't start. Check that the site is reachable, then try again." (setup_failed) and "Something went wrong on our side while auditing." (anything else).

A site that is unreachable, or that blocks SEOFix, usually does not fail the audit. The audit finishes as done with fetch errors, broken pages or firewall-blocked pages in the report. See /help/blocked-pages for firewalls.

#Partial is not a status

A done report can be partial (partial: true): it reached its page limit, or a preview hit its 50-page or 60-second cap. The results are valid for the pages crawled. Raise the site's Page limit to cover more (/help/crawl-settings).

#Cancelling

• In the app: "Cancel audit" on the audit page while it is queued or running, then confirm "Cancel audit". "Keep running" closes the dialog.
• Agents: cancel_audit (MCP) or DELETE /v1/crawls/{id}. Any member of the audit's team can cancel it.

curl -X DELETE https://api.seofix.ai/v1/crawls/1843 \
  -H "Authorization: Bearer $SEOFIX_API_KEY"

{ "status": "cancelled" }

An audit that already ended answers 409 conflict ("Crawl has already reached a terminal state and cannot be cancelled."). The crawler stops within a few seconds; pages saved until then are kept and charged, and no report is built.

#Credits when an audit ends

When an audit starts, SEOFix reserves credits equal to its page limit (credits_reserved). About a minute after it ends, whatever the outcome (done, failed or cancelled), it charges:

charge = pages crawled − pages answered 304 + ceil(pages answered 304 ÷ 5)
refund = credits_reserved − charge

The refund goes back to whoever was charged: the team owner for audits of a team's site, or the person who started an audit of a plain URL. An audit that failed before crawling anything is refunded in full. Previews and the free audit reserve nothing and charge nothing; cancelling the free audit does not give it back.

#Restarts on SEOFix's side

If a crawler restarts while your audit runs, the audit goes back to queued and later starts again from the beginning, with its partial results cleared. Nothing extra is charged: only the pages of the final run count.

#Webhooks

An audit started through the API with a webhook_url gets a POST to that URL when it ends as done, failed or cancelled, with crawl_id, status, pages_crawled and health_score, signed in the X-Audit-Signature header. See /help/webhooks.

#Related

• /help/how-the-crawler-works
• /help/reading-your-report
• /help/crawl-settings
• /help/plans-and-credits