---
title: "List findings"
method: GET
path: "/brands/{brandId}/findings"
tags: ["findings"]
---

# List findings

`GET /brands/{brandId}/findings`

## Request

- Base URL: `https://shruwd.io/api/v1`
- URL: `https://shruwd.io/api/v1/brands/{brandId}/findings`
- Auth: HTTP bearer

Ordered by severity, then confidence, then estimated impact — the same
order the dashboard and the weekly digest use. By default the open,
acknowledged, fix-applied and rechecking findings; `states` narrows or
widens that. Suppressed findings (a more fundamental finding explains
them) are hidden unless `suppressed=1`.

`confidence`: `observed` means measured directly from first-party data;
`inferred` means derived from a reliable pattern; `heuristic` means a
plausible cause that could not be confirmed. Treat `heuristic` as a
hypothesis to test, not a fact.

## Query parameters

- `states` string
- `suppressed` '1'

## Response `200`

Findings.

- FindingList
  - `brand` object, required
    - `brandId` string, required
    - `name` string, required
    - `domain` string, required
  - `findings` Finding[], required
    - `findingId` string, required
    - `number` integer, required: 1, 2, 3… per workspace, never reused. The dashboard links by it (/brands/{slug}/findings/{number}) and `{findingId}` accepts it.
    - `ruleId` string, required
    - `family` 'ACCESS' | 'STRUCT' | 'CITE' | 'FACT' | 'COVERAGE', required
    - `severity` 'critical' | 'high' | 'medium' | 'low', required
    - `confidence` 'observed' | 'inferred' | 'heuristic', required: `observed` — measured from first-party data. `inferred` — a reliable pattern. `heuristic` — plausible, unconfirmed; treat as a hypothesis.
    - `state` 'open' | 'acknowledged' | 'fix_applied' | 'rechecking' | 'resolved' | 'not_moved' | 'dismissed' | 'stale', required
    - `subjectType` 'url' | 'prompt_group' | 'domain' | 'brand', required
    - `subjectRef` string, required
    - `evidence` object, required: What the rule saw. Shape depends on `ruleId`.
    - `recommendation` Recommendation, required
      - `summary` string, required
      - `steps` string[], required
      - `target` string, nullable, required: The specific artifact to change: a URL, a file, a setting. Null on a finding about a question when no page of the brand's is cited for it and none is set: the steps say so. Set one with `PATCH /prompts/{promptGroupId}` (`page`); the finding's `subjectRef` is that id.
      - `expectedMetric` string, required: Which metric should move if the fix works.
    - `firstSeenAt` string, date-time, required
    - `lastSeenAt` string, date-time, required
    - `suppressedBy` string, nullable, required: The finding that explains this one, when suppressed.
    - `surfaced` boolean, required: False while the finding waits behind the weekly cap.
    - `estimatedImpact` number, required
  - `counts` object, required: Findings per state, across all states.
  - `queued` integer, required: Open findings not yet surfaced because of the weekly cap.
  - `locked` object, required: Findings the plan does not show in full (`maxVisibleFindings`): counted, never sent.
    - `count` integer, required
    - `bySeverity` object, required
    - `limit` integer, nullable, required

## Other responses

- `404`: `not_found`: no such resource in this workspace.
- `default`: Every failure has this body.

---

[API](https://skmtc.dev/shruwd/apis/shruwd-api.md) · [All operations](https://skmtc.dev/shruwd/apis/shruwd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shruwd/apis/shruwd-api/revisions/64a5da079928?raw)