get_page_audit

get_page_audit fetches one page optimization by its auditId, the id returned by run_page_audit. While the optimization runs, it returns its status; once COMPLETED, it returns what changed on the page and why, the passages to check on the live page, the facts the page still needs, and on request the optimized page itself.

When to use

Poll it after run_page_audit until isComplete is true. Then show the user the changes, and fetch the page with include.page when they want to paste it. Legacy page audits (created before September 2026) are still readable with the same tool and keep their original shape (version 1 or 2).

Input

The page and the JSON-LD are opt-in: they are the heavy part of the response, and most calls only need the changes.

Response

Running

{
  "success": true,
  "auditId": "clx_page_42",
  "version": 3,
  "status": "GENERATING",
  "isComplete": false,
  "pageUrl": "https://example.com/services",
  "prompt": { "id": "clx_prompt_7", "text": "best web designer for craftsmen" },
  "message": "Optimization still running, typically 1 to 2 minutes. Poll this tool again.",
  "createdAt": "2026-09-29T10:00:00.000Z",
  "updatedAt": "2026-09-29T10:00:05.000Z"
}

Completed

{
  "success": true,
  "auditId": "clx_page_42",
  "version": 3,
  "status": "COMPLETED",
  "isComplete": true,
  "pageUrl": "https://example.com/services",
  "prompt": { "id": "clx_prompt_7", "text": "best web designer for craftsmen" },
  "title": "Websites for craftsmen",
  "changes": [
    {
      "what": "Open with one sentence that says who runs the studio and who it builds sites for.",
      "why": "The engines cite pages that name the business and its trade; this one never says who speaks.",
      "fanOut": "web designer for craftsmen"
    }
  ],
  "textIssues": [
    { "excerpt": "plumbersmasonsroofers", "issue": "Animated text captured several times by the extraction." }
  ],
  "gaps": [{ "where": "Pricing", "whatToFind": "What the one-off site price includes" }],
  "appliedAt": null,
  "page": "## Websites for craftsmen\n\n...",
  "createdAt": "2026-09-29T10:00:00.000Z",
  "updatedAt": "2026-09-29T10:01:32.000Z"
}

• changes: 5 to 7, most useful first. fanOut is the fan-out query the change serves, or null.
• textIssues: passages misread when the page was extracted. They are left as they are in the page: check them on the live page.
• gaps: facts the optimized page needs and nothing gives (a price, an address, a result). The page marks them [data to add: ...].
• appliedAt: when the user marked the changes as applied, null before.
• page and jsonLd: only with include.page / include.jsonLd.

A FAILED optimization returns errorMessage instead of the result fields.

Error

{ "success": false, "error": "audit_not_found", "message": "No page audit with this id is attached to the given project." }

Tips and patterns

• Show the changes first. They are the explanation the user reads; the page is the deliverable they paste.
• Fetch the page once. Ask for include.page only when the user wants it, not on every poll.
• Flag the gaps. Each [data to add: ...] marker in the page is a fact only the user can provide.

Related tools

• run_page_audit: start an optimization.
• list_page_audits: browse past optimizations.