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.

Request body required

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`).

id string required

status string required

createdAt string (date-time) required

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"
}

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

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

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

{}

Edit this page