# Checks_ListCheckFindings

`GET /v1/accounts/{account}/datasets/{dataset}/checks/{check}/findings`

Lists the findings catalog checks wrote on a dataset, newest first: one
per check, episode and finding key per run. The check may be `-` for
every check's. Findings written before the catalog (templates)
are listed under the check their template maps to, with `legacy` set.

By default only the findings that stand: for each check and episode,
those of the newest run of that check (by start) that read the episode
at its linked revision, the Task and revision its link carries
(Episode.linked_task_revision: its own link's, else its dataset's).
Publishing a newer revision changes nothing; after a relink an episode
has none until a run reads the new revision. A draft link carries no
revision, nor does an episode with no link: there a finding stands while
its Task is published at the revision it read (a draft's until the Task
is first published), and one whose Task the workspace no longer has has
no newer revision. Under any link only the linked Task's findings stand:
a link moved to another Task, published or not, leaves none until a run
reads that Task. A finding with no Task has no revision. A heuristic
check has no Task revision: its findings are its issues, each as its
newest run left it. The filter `all_revisions = true` lists every run's
findings.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header

## Parameters

- `account` (path, string, required): The account id.
- `dataset` (path, string, required): The dataset id.
- `check` (path, string, required): The check id.
- `pageSize` (query, integer (int32)): At most this many; 0 means 100, the maximum is 1000.
- `pageToken` (query, string): From a previous response's next_page_token.
- `filter` (query, string): AIP-160 filter. Fields: check_run, episode (names, `=`), verdict, and
  all_revisions (`true` lists superseded runs' findings too; default
  `false`: only the findings that stand). Terms join with AND.

## Responses

- `200` OK: `application/json` `qualia.v1.ListCheckFindingsResponse`
- `default` Default error response: `application/json` `google.rpc.Status`

## Schemas

```yaml
qualia.v1.ListCheckFindingsResponse:
  type: object
  properties:
    checkFindings:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.CheckFinding"
      description: One page of findings, newest first.
    nextPageToken:
      type: string
      description: Empty on the last page.
  description: Response for Checks.ListCheckFindings.
qualia.v1.CheckFinding:
  type: object
  properties:
    name:
      type: string
      description: accounts/{account}/datasets/{dataset}/checks/{check}/findings/{finding}
    checkRun:
      readOnly: true
      type: string
      description: "accounts/{account}/checks/vlm/runs/{run}: the run that wrote it."
    checkVersion:
      readOnly: true
      type: integer
      description: The check version that wrote it; 0 for a legacy finding.
      format: int32
    legacy:
      readOnly: true
      type: boolean
      description: |-
        Whether it was written by a template before the catalog; its
        check is the one the template maps to.
    episode:
      readOnly: true
      type: string
      description: accounts/{account}/datasets/{dataset}/episodes/{episode}
    findingKey:
      readOnly: true
      type: string
      description: Stable within the check, e.g. `success_1` for a criterion.
    verdict:
      readOnly: true
      enum:
        - VERDICT_UNSPECIFIED
        - PASS
        - FAIL
        - UNKNOWN
      type: string
      description: What it found.
      format: enum
    confidence:
      readOnly: true
      type: number
      description: 0 to 1.
      format: float
    severity:
      readOnly: true
      enum:
        - SEVERITY_UNSPECIFIED
        - NONE
        - NOTE
        - ISSUE
      type: string
      description: What it raised.
      format: enum
    title:
      readOnly: true
      type: string
      description: A few words.
    summary:
      readOnly: true
      type: string
      description: One sentence.
    explanation:
      readOnly: true
      type: string
      description: The evidence, in a few sentences.
    taskRevision:
      readOnly: true
      type: string
      description: |-
        accounts/{account}/tasks/{task}/revisions/{revision}: the Task revision
        it read against, for a Task check; the Task's name for one read against
        its unpublished draft; empty otherwise.
    issue:
      readOnly: true
      type: string
      description: |-
        accounts/{account}/datasets/{dataset}/issues/{issue}: the issue or note
        it raised; empty for a pass.
    createTime:
      readOnly: true
      type: string
      description: When it was written.
      format: date-time
  description: |-
    One finding a catalog check wrote on an episode. Its issue
    identity is the dataset, episode, check id and finding key: a re-run of a
    check updates only that check's issues, and a skipped episode leaves them
    as they were.

    Served by qds-api.
google.rpc.Status:
  oneOf:
    - $ref: "#/components/schemas/ApiError"
    - $ref: "#/components/schemas/GatewayError"
  description: "The body of a failed call: one of the two shapes below."
ApiError:
  title: API error
  type: object
  required:
    - code
    - message
    - retryable
    - details
  properties:
    code:
      type: string
      description: The gRPC code name in upper case, e.g. `NOT_FOUND`.
    message:
      type: string
    retryable:
      type: boolean
      description: Whether the same call may succeed if retried.
    details:
      type: array
      items:
        type: object
      description: "Empty, except when a dataset copy or move is refused: then one `google.rpc.ErrorInfo` with the refusal's `reason` code, its `domain` and, in `metadata`, the datasets it names."
  description: A refusal from the API itself.
GatewayError:
  title: Gateway error
  type: object
  required:
    - detail
  properties:
    detail:
      type: string
      description: What went wrong.
  description: A refusal from the gateway before the call reaches the API, for example `401` bad or missing API key, `403` key lacks the scope or environment closed, `413` body too large.
```