---
title: "Get an audit run"
method: GET
path: "/v1/agent-runs/{id}"
tags: ["Audits"]
---

# Get an audit run

`GET /v1/agent-runs/{id}`

## Request

- Base URL: `https://api.squirrelscan.com`
- URL: `https://api.squirrelscan.com/v1/agent-runs/{id}`
- Auth: HTTP bearer

Fetch full detail for a single audit run owned by the authenticated user. While `status` is `pending`/`running`, `progress` carries the latest phase/page-count event streamed by the run, when one has been recorded. `notice` carries a `page_limit_clamped` signal when the run's requested page count was clamped down to the org's plan ceiling at dispatch time (never a hard error — the run itself still completed normally). `renderFallback` carries a `render_fallback` signal, with the page count, when pages that asked for rendering were audited from their unrendered source instead.

## Path parameters

- `id` string, required

## Response `200`

The audit run.

- AuditRun: Audit run as returned by the list endpoint. Also the shared base for the single-run `AuditRun` schema, which composes this plus `userId`/`orgId` via `allOf` — so the common fields live in exactly one place. Nullable fields are unset until the run progresses.
  - `id` string, required
  - `url` string, uri, required
  - `status` 'pending' | 'running' | 'completed' | 'failed' | 'cancelled', required
  - `trigger` 'cli' | 'api' | 'github' | 'scheduled', required
  - `mode` 'audit' | 'audit-fix' | 'fix' | 'recommend', required
  - `model` string, nullable
  - `healthScore` integer, nullable: Rounded score from the persisted `health_score` DB column (an integer). The unrounded float is available as `report.healthScore` on `GET /v1/agent-runs/{id}/report`.
  - `issuesFound` integer, nullable
  - `issuesFixed` integer, nullable
  - `reportId` string, nullable
  - `websiteId` string, nullable
  - `auditId` string, nullable
  - `config` object, nullable
  - `error` string, nullable
  - `completionReason` string, nullable
  - `completionMessage` string, nullable
  - `costUsd` number, nullable
  - `startedAt` string, date-time, nullable
  - `completedAt` string, date-time, nullable
  - `createdAt` string, date-time, required
  - `userId` string, required: Internal owner user id (the caller's own — runs are scoped to the authenticated user). Treat as an opaque identifier; do not log/forward outside an authenticated context.
  - `orgId` string, nullable
  - `progress` object, nullable: Live progress while `status` is `pending`/`running` (#692): the latest phase/page-count event streamed by the run. Null once the run is terminal, or if no progress event has been recorded yet.
    - `phase` string, nullable
    - `message` string, nullable
    - `current` integer, nullable
    - `total` integer, nullable
    - `failed` integer, nullable
    - `updatedAt` string, date-time
  - `notice` PageLimitClampNotice: 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.
    - `type` 'page_limit_clamped', required
    - `requested` integer, required: Pages that were actually asked for (stored crawl config or an explicit request override).
    - `applied` integer, required: Pages the run actually dispatched with — equal to `planCap`.
    - `planId` 'free' | 'starter' | 'team', required
    - `planCap` integer, required: The org's plan's effective max-pages-per-audit ceiling at dispatch time.
    - `upgradeHint` string, required: Human-readable upgrade suggestion, always including a pricing URL.
  - `renderFallback` RenderFallbackNotice: Present only when pages the run asked to render could not be rendered and were audited from their unrendered source instead. The audit still completes and publishes; content added by JavaScript was not seen on those pages. Absent when every render succeeded or the run never asked for rendering.
    - `type` 'render_fallback', required
    - `pages` integer, required: Pages that fell back to plain fetch.
    - `message` string, required: Human-readable explanation, suitable to show to the audit's owner.

## Other responses

- `401`: Missing or invalid credentials (including the shared auth middleware: no/invalid bearer token). Typed envelope with code `UNAUTHORIZED`. Branch on the `401` status, not the message.
- `404`: Resource not found (or hidden from the caller).
- `429`: Too many requests. Retry after the window resets. (Rate limiting is planned — issue #69 — these headers document the intended contract.)

---

[API](https://skmtc.dev/squirrelscan/apis/squirrelscan-public-api.md) · [All operations](https://skmtc.dev/squirrelscan/apis/squirrelscan-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/squirrelscan/apis/squirrelscan-public-api/revisions/82c8183fe8bc?raw)