Create an audit run
Start a cloud audit run
/v1/agent-runsStart a new cloud audit run. Send a `url` and, optionally, a `config` object (for example `{"maxPages":1,"enabledRulePatterns":["ax/*","core/robots-meta"],"disabledRulePatterns":["ai/page-type-match","ai/site-metadata","ai/llm-parsability"],"render":false,"externalLinksEnabled":false,"ephemeral":true}`). With an API key the run is dispatched to the cloud crawler immediately (`trigger` defaults to `api`) and progresses asynchronously; poll `GET /v1/agent-runs/{id}` for status. Cloud features are credit-gated. If the requested page count exceeds the org's plan ceiling, the run still starts at the plan's max (clamp, never a hard error) and the response carries a `notice` field (`type: "page_limit_clamped"`) saying so. A request the API cannot honour as written (an unknown `config` key, a rule pattern that matches nothing, a selection that leaves no rule to run) is a 400 `VALIDATION_ERROR` and nothing is charged or started.
Request bodyrequired
urlstring (uri)requiredSite URL to audit.
trigger"api"default: apiRun origin. Optional for an API key, which gets `api` (it dispatches the cloud crawler) whether it sends it or not. A signed-in session must send it: omitting it is a 400. (`cli`/`github`/`scheduled` are internal-origin values that skip cloud dispatch and are not accepted here.)
Available options: api
modeanydefault: auditmodelstringconfigobject | stringOptional run config: an object (preferred) or the same object as a JSON-encoded string (the older form, still accepted). A string that is not valid JSON, a value that is not an object, a key outside `CreateAuditRunConfig`, or a wrongly typed or invalid value is a 400 `VALIDATION_ERROR` (nothing is started or charged); it is never silently ignored. The config a run reports back in `GET /v1/agent-runs/{id}` can be sent again: the keys the server writes into it (listed in `CreateAuditRunConfig`) are accepted and dropped, and the run's own values are used instead. A completed run's config can also hold keys written during the run (timings, billing, failure detail); those are not accepted.
websiteIdstringauditIdstringResponses
Run created (status `pending`).
idstringrequiredstatus"pending" | "queued"required`pending` once dispatched; `queued` when the run is waiting for a container slot and starts by itself (the response then carries `queue`).
Available options: pending, queued
createdAtstring (date-time)requirednoticeobjectPresent only when the run's requested page count exceeded the org's plan ceiling. The run is never rejected for this (clamp-and-notify, not a hard error) — it dispatches at `applied` pages instead of `requested`, and this field says so.
disabledRulePatternsstring[]The disable list this request sent, as expanded. Present only when `config.disabledRulePatterns` was sent and not empty.
enabledRulePatternsstring[]The include filter the run applies, as expanded (`ax` becomes `ax/*`). Present only when `config.enabledRulePatterns` was sent.
renderbooleanWhether the run renders pages. Present only when `config.render` was sent.
ephemeralbooleanWhether the one-shot treatment applies. Present only when `config.ephemeral` was sent.
ephemeralIgnoredReasonstringWhy `ephemeral` was not honoured, when `ephemeral` is `false`.
editorSummarybooleanWhether the run builds the editor's summary. Present only when `config.enabledRulePatterns` or `config.editorSummary` was sent.
editorSummarySkippedReason"rule-filtered run" | "disabled by the run config"Why the summary is skipped, when `editorSummary` is `false`.
Available options: rule-filtered run, disabled by the run config
curl --request POST \
--url "https://api.squirrelscan.com/v1/agent-runs"{
"id": "<string>",
"status": "pending",
"createdAt": "2023-11-07T05:31:56Z",
"notice": {
"type": "<string>",
"requested": 123,
"applied": 123,
"planId": "free",
"planCap": 123,
"upgradeHint": "<string>"
},
"disabledRulePatterns": [],
"enabledRulePatterns": [],
"render": true,
"ephemeral": true,
"ephemeralIgnoredReason": "<string>",
"editorSummary": true,
"editorSummarySkippedReason": "rule-filtered run"
}