API Reference

Audit Status

Poll the status of an audit job as it progresses through the pipeline.

GET/api/v1/audits/[slug]/status

Check the current status of an audit job. Use this to poll after submitting a new audit or requesting a re-audit.

Path Parameters

Name	Type	Required	Description
`slug`	string	Required	Domain slug (e.g., "notion-com")

Status Progression

Audits move through these stages in order. Poll the status endpoint to track progress.

Status	Description
`pending`	Queued, waiting for a worker
`discovering`	Finding competitor domains and classifying taxonomy
`auditing`	Running the AEO audit against the current criteria set
`seeding`	Storing results in the database
`visibility`	Generating AI visibility report
`completed`	Audit finished, results available
`failed`	Audit failed (see error details)

Example

bash

curl "https:">//audit.aeocontent.ai/api/v1/audits/example-com/status" \
  -H "Authorization: Bearer $AEO_API_KEY"

Try it

Response

While the audit is running, current_stage indicates the active pipeline step and overall_score is null.

200Audit in progress

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"status": class="code-string">"pending",
    class="code-string">"current_stage": class="code-string">"auditing",
    class="code-string">"overall_score": null,
    class="code-string">"started_at": class="code-string">"2026-02-22T12:00:00.000Z",
    class="code-string">"completed_at": null
  },
  class="code-string">"meta": {
    class="code-string">"request_id": class="code-string">"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    class="code-string">"timestamp": class="code-string">"2026-02-22T12:00:00.000Z"
  }
}

Once the audit finishes, overall_score contains the final AEO Site Rank (0-100) and completed_at is populated.

200Audit completed

json

{
  class="code-string">"data": {
    class="code-string">"slug": class="code-string">"example-com",
    class="code-string">"status": class="code-string">"completed",
    class="code-string">"current_stage": null,
    class="code-string">"overall_score": 72,
    class="code-string">"started_at": class="code-string">"2026-02-22T12:00:00.000Z",
    class="code-string">"completed_at": class="code-string">"2026-02-22T12:05:30.000Z"
  },
  class="code-string">"meta": {
    class="code-string">"request_id": class="code-string">"c3d4e5f6-a7b8-9012-cdef-123456789012",
    class="code-string">"timestamp": class="code-string">"2026-02-22T12:05:31.000Z"
  }
}

404Not found

json

{
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"not_found",
    class="code-string">"message": class="code-string">"No job or audit found for slug 'unknown-com'."
  }
}

Poll at 30-second intervals. Audits typically complete within 3-5 minutes.