Create an audit run

Start a cloud audit run

POST/v1/agent-runs

Start a new cloud audit run. With `trigger: "api"` the run is dispatched to the cloud crawler immediately 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.

Request bodyrequired

urlstring (uri)required

Site URL to audit.

trigger"api"required

Run origin. Public API callers must send `api`, which dispatches the cloud crawler. (`cli`/`github`/`scheduled` are internal-origin values that skip cloud dispatch and are not accepted here.)

Available options: api

modeanydefault: audit

modelstring

configstring

Optional run config as a JSON-**encoded string** (not a nested object — the field is parsed server-side). Keys: coverageMode, maxPages, disabledRulePatterns, externalLinksEnabled. NOTE the round-trip asymmetry: you send a string here, but `AuditRun.config` is returned as a parsed object.

websiteIdstring

auditIdstring

Responses

Run created (status `pending`).

idstringrequired

statusstringrequired

createdAtstring (date-time)required

noticeobject

Present 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.

curl --request POST \
  --url "https://api.squirrelscan.com/v1/agent-runs"

const res = await fetch("https://api.squirrelscan.com/v1/agent-runs", {
  method: "POST",
});
const data = await res.json();

import requests


r = requests.post("https://api.squirrelscan.com/v1/agent-runs")
r.raise_for_status()
data = r.json()

{
  "id": "<string>",
  "status": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "notice": {
    "type": "<string>",
    "requested": 123,
    "applied": 123,
    "planId": "free",
    "planCap": 123,
    "upgradeHint": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{}

Edit this page