A script deciding whether an audit needs human attention may not need every finding, fix, and peer detail. Passing the full report through each step adds information the next decision may never use.
MachineRead offers POST /v1/audit/summary for that case. It runs the same Essentials pipeline as POST /v1/audit, then selects a smaller set of structured fields. It does not skip checks or ask a language model to rewrite the findings (MachineRead, "API Reference").
What the compact response keeps
The compact response has its own strict model. A successful AuditSummary exposes exactly these top-level fields: api_version, summary_version, url, scope, scores, benchmarks, checks, attention, and limitations.
Those fields are selected for a bounded next-step decision. The response keeps the normalized URL, compact resolved scope, score and denominator pairs, Essentials and strict-readiness benchmark summaries, report-row counts, up to five attention rows, and fixed limitation codes.
That is enough for a client to answer practical questions such as:
- Which URL did MachineRead evaluate?
- What scope did the request resolve to?
- What were the Essentials and strict-readiness scores?
- How many checks passed, warned, failed, or were locked?
- Which few included, non-passing, non-locked rows need attention first?
- Which standard limitations should travel with the response?
The answer is deliberately compact. It is not trying to reproduce the full report in a different order.
What the compact response leaves out
The compact response leaves out per-row finding and fix prose, check display labels, benchmark entries, nearest, basis, and caveat, agent-readiness passed, missing, and not_checked lists, rate-limit body metadata, and raw fetch context.
Choose the full POST /v1/audit response if the next step needs any of that detail. For example, a notification can use the compact attention list, but someone preparing a repair needs the findings and fix guidance.
It is a deterministic projection, not an AI summary
The summary selects fields from the completed audit result according to fixed rules. It does not generate new finding prose or reinterpret a failed check. That makes the output suitable for software that needs named fields rather than a paragraph to parse.
The response still needs careful handling. Keep its API and summary versions, preserve the score denominators, and distinguish an unavailable observation from a failure. A smaller payload does not remove the audit's limitations.
The rate-limit boundary is shared
Full and compact REST audits share the same per-client audit limit. Switching endpoints does not create a second quota pool. Handle a 429 response using the returned retry guidance rather than immediately trying the other endpoint (MachineRead, "API Reference").
Choose the route for the information you need. The compact route still runs the audit, so its smaller response is not a promise of a faster scan.
Choosing full or compact
Use the full audit response when the next step needs report detail: row findings, fix prose, full benchmark context, or the broader explanatory material that helps a human inspect the site.
Use the compact audit response when the next step needs stable structured signals: scores, scope, counts, two compact benchmark summaries, the capped attention list, and limitation codes. That is a better fit for a workflow that needs to decide whether to notify a human, store a status record, compare repeated runs, or choose which small set of rows to inspect first.
Both choices start from the same canonical audit execution. The difference is the response contract that follows it.
Preserve the fields that explain the number
Send the same request body to either route, for example:
{"url":"https://example.com/","preset":"blog"}
This is an illustrative request, not a recorded audit result. The API reference supplies the endpoint addresses and complete response models.
A consumer of the compact response should inspect scores.essentials with its earned and max values, then read attention for the selected rows. The list is capped at five; it is not a complete inventory of every issue. Use the full report when someone needs the finding and fix prose. Also note the naming difference: the full response uses singular benchmark, while the compact response groups its two comparisons under plural benchmarks.
Works Cited
MachineRead. "API Reference." MachineRead, https://www.machineread.ai/docs/api. Accessed 10 Sept. 2026.
See also
- How an OpenAPI document makes an API easier to inspect - explains API descriptions as inspectable contracts
- Choose the checks that fit the site - explains resolved scope before audit execution
- What a MachineRead benchmark compares - separates compact benchmark summaries from fuller peer context