Findings Endpoints

Findings are the individual audit results the crawler produces — one row per URL per rule. Use the /v1/findings endpoint to retrieve them programmatically, filter by severity or rule, and page through large result sets.

List findings

GET /v1/findings

Returns a paginated list of findings. By default, the response includes findings from the latest completed pass for each site visible to your API key. When a passId is specified, the scope narrows to that single crawl pass.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`50`	Number of findings per page. Maximum `200`.
`cursor`	string	—	Opaque cursor from a previous response's `nextCursor`. Do not construct or store cursors beyond the current pagination run.
`siteId`	UUID	—	Restrict results to a single site.
`severity`	string	—	Filter by severity level: `critical`, `warning`, or `notice`.
`rule`	string	—	Filter by rule key, e.g. `title_missing`. See the rules reference for a full list of keys.
`passId`	UUID	—	Restrict results to a specific crawl pass. When set, the response `scope` changes to `pass`.

Filtering

Filters compose with logical AND — specifying both severity and siteId returns only findings that match both conditions.

Scope

The default scope is latestPassPerSite: findings are drawn from the most recent completed crawl pass for each site. This gives a current picture without requiring you to look up pass IDs first.

When passId is included in the query, the scope changes to pass and only findings from that specific crawl are returned. The scope field in the response always reflects which mode was used.

Common filter combinations

Goal	Parameters
All critical findings across every site	`?severity=critical`
Findings for a single site	`?siteId=uuid`
Findings from a specific crawl pass	`?passId=uuid`
A single rule across all sites	`?rule=title_missing`
Critical findings for one site	`?siteId=uuid&severity=critical`

Response format

Successful requests return a JSON envelope containing the findings array, a pagination cursor, and the scope that was applied:

{
  "data": [
    {
      "id": 48291,
      "passId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
      "siteId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "host": "example.com",
      "rule": "title_missing",
      "severity": "warning",
      "url": "https://example.com/about",
      "statusCode": 200
    }
  ],
  "nextCursor": "eyJpZCI6NDgzMDB9",
  "scope": "latestPassPerSite"
}

Finding fields

Field	Type	Description
`id`	i64	Unique identifier for this finding.
`passId`	UUID	The crawl pass that produced this finding.
`siteId`	UUID	The site this finding belongs to.
`host`	string	The hostname of the inspected URL.
`rule`	string	The rule key that triggered. See the rules reference.
`severity`	string	One of `critical`, `warning`, or `notice`.
`url`	string	The full URL where the finding was observed.
`statusCode`	integer \| null	The HTTP status code of the response, or `null` when the finding is not about a response (e.g. a DNS or connection-level issue).

Each finding is an individual row — one per URL per rule. The API does not aggregate or group counts; for grouped views, the cloud dashboard aggregates client-side.

Examples

Fetch the first page of all findings

curl https://api.consuela.io/v1/findings \
  -H "Authorization: Bearer csl_live_abc123..."

Filter by severity

curl "https://api.consuela.io/v1/findings?severity=critical" \
  -H "Authorization: Bearer csl_live_abc123..."

Findings for a specific site

curl "https://api.consuela.io/v1/findings?siteId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer csl_live_abc123..."

Findings from a specific crawl pass

curl "https://api.consuela.io/v1/findings?passId=d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90" \
  -H "Authorization: Bearer csl_live_abc123..."

When passId is present, the response scope will be pass instead of latestPassPerSite.

A specific rule across all sites

curl "https://api.consuela.io/v1/findings?rule=title_missing" \
  -H "Authorization: Bearer csl_live_abc123..."

Paginate through results

curl "https://api.consuela.io/v1/findings?limit=100&cursor=eyJpZCI6NDgzMDB9" \
  -H "Authorization: Bearer csl_live_abc123..."

Pass the nextCursor value from the previous response as the cursor parameter. When nextCursor is null, there are no more pages.