# Checks_CancelCheckRun

`POST /v1/accounts/{account}/checks/{check}/runs/{run}:cancel`

Cancels a running VLM or heuristic run: its pipeline run is
cancelled, which releases the credits it reserved, and the run ends
FAILED with "cancelled by" who asked. A VLM run still QUEUED behind
another ends so at once: it never starts and reserves nothing. Episodes
it had not read keep their issues. The check may be `-`: a run's id
names one run. Needs what RunCheck needs (a write on the dataset).
FAILED_PRECONDITION for a run that has ended, one still starting its
pipeline run (ask again in a few seconds) and any other check's run. A
pipeline cancel that answered late or failed but took ends the run all
the same. UNAVAILABLE when the pipeline could not be reached or did not
answer in time and the run does not read cancelled after: it still runs;
ask again. ABORTED when another cancel or end of a queued run keeps it
busy: nothing changed; ask again. NOT_FOUND outside the caller's
workspace.

- 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.
- `check` (path, string, required): The check id.
- `run` (path, string, required): The run id.

## Request body

Required: `application/json` `qualia.v1.CancelCheckRunRequest`

## Responses

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

## Schemas

```yaml
qualia.v1.CancelCheckRunRequest:
  required:
    - name
  type: object
  properties:
    name:
      type: string
      description: accounts/{account}/checks/{check}/runs/{run} (check may be `-`).
  description: Request for Checks.CancelCheckRun.
qualia.v1.CheckRun:
  type: object
  properties:
    name:
      type: string
      description: accounts/{account}/checks/{check}/runs/{run}
    dataset:
      readOnly: true
      type: string
      description: |-
        accounts/{account}/datasets/{dataset}: the dataset it checked (an
        upload, for each per-upload run of a merged dataset).
    operation:
      readOnly: true
      type: string
      description: |-
        accounts/{account}/operations/{operation}: the same id, as
        RunCheckResponse.operation and the record's events name it.
    state:
      readOnly: true
      enum:
        - STATE_UNSPECIFIED
        - QUEUED
        - RUNNING
        - SUCCEEDED
        - FAILED
      type: string
      description: Where it stands.
      format: enum
    failureReason:
      readOnly: true
      type: string
      description: Why it failed; empty otherwise.
    selectedCount:
      readOnly: true
      type: integer
      description: Episodes of the selection; 0 when it checked the whole dataset.
      format: int32
    raisedCount:
      readOnly: true
      type: integer
      description: |-
        Issues and notes it opened (new ones, and ones a re-run had closed);
        set once it succeeded.
      format: int32
    resolvedCount:
      readOnly: true
      type: integer
      description: |-
        Open issues and notes it no longer found, dismissed as RESOLVED; set
        once it succeeded.
      format: int32
    creator:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Actor"
      description: Who started it.
    createTime:
      readOnly: true
      type: string
      description: When RunCheck recorded it.
      format: date-time
    updateTime:
      readOnly: true
      type: string
      description: When it last moved; once it ended, when it ended.
      format: date-time
    judgedTasks:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.CheckRun_JudgedTask"
      description: |-
        The Task revisions it judged against, set once it planned: a VLM run's
        Tasks, and the ones a heuristic run read duration bounds from. A run
        judges each Task at the revision its episodes' links carry, never a newer
        one; empty when it read no Task.
    vlm:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.CheckRun_Vlm"
      description: The VLM check's.
  description: |-
    One run of a check over a dataset, as RunCheck recorded it. Its
    id is the operation's (RunCheckResponse.operation), so its events on the
    record name it too. A merged dataset is checked one upload at a time, one
    run each, named under the upload, but for VLM and REACH, which are one run
    named under the merged dataset.

    Served by qds-api.
qualia.v1.Actor:
  type: object
  properties:
    kind:
      readOnly: true
      enum:
        - KIND_UNSPECIFIED
        - PERSON
        - VALIDATION
        - RULE
        - MODEL
        - OPERATOR
        - SYSTEM
      type: string
      description: What kind of actor it is.
      format: enum
    user:
      readOnly: true
      type: string
      description: The person's user id when `kind` is PERSON; empty otherwise.
    displayName:
      readOnly: true
      type: string
      description: The person's display name at the time, for rendering without a lookup.
    agent:
      readOnly: true
      type: string
      description: |-
        The rule code, or for a MODEL the Qualia model tier (e.g. "qualia-vlm";
        "qualia" for any other model), when not a person.
    run:
      readOnly: true
      type: string
      description: The run a model or rule finding came from, when it has one.
    apiKey:
      readOnly: true
      type: string
      description: |-
        The API key's id when a person acted through one; empty for a session.
        Never the key itself.
    attribution:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Attribution"
      description: |-
        Signed identity evidence recorded with the change, kept apart from the
        principal above. Unset on older records and wherever none was signed.
  description: Who did something. Every decision, issue and reply names one.
qualia.v1.Attribution:
  type: object
  properties:
    authentication:
      readOnly: true
      enum:
        - AUTHENTICATION_UNSPECIFIED
        - SESSION
        - API_KEY
        - SERVICE
      type: string
      description: How the principal authenticated.
      format: enum
    initiator:
      readOnly: true
      type: string
      description: |-
        The user id of a person verified as starting the work: the person of a
        session, or the person a trusted service's signed job record names.
        Empty when nobody was verified.
    initiatorDisplayName:
      readOnly: true
      type: string
      description: The initiator's display name at the time, never their email.
    credentialCreator:
      readOnly: true
      type: string
      description: The user id of the key's creator at the time. Not who used the key.
    credentialOwner:
      readOnly: true
      enum:
        - CREDENTIAL_OWNER_UNSPECIFIED
        - PERSON
        - SPACE
      type: string
      description: Who owned the key at the time.
      format: enum
    credentialOwnerSpace:
      readOnly: true
      type: string
      description: |-
        The owning space's id (a workspace or the organization) when
        `credential_owner` is SPACE.
  description: |-
    How a change was authenticated and who verifiably started it.
    Only the trusted mesh signs it. It never authorizes anything, and a key's
    creator or owner is never the person who used the key.
qualia.v1.CheckRun_JudgedTask:
  type: object
  properties:
    task:
      readOnly: true
      type: string
      description: accounts/{account}/tasks/{task}
    displayName:
      readOnly: true
      type: string
      description: The Task's display name, as that revision (or draft) has it.
    revision:
      readOnly: true
      type: integer
      description: |-
        The revision the episodes' links carry (Episode.linked_task_revision);
        0 when the run read the Task's unpublished draft.
      format: int32
  description: A Task revision a run judged its episodes against.
qualia.v1.CheckRun_Vlm:
  type: object
  properties:
    model:
      readOnly: true
      type: string
      description: |-
        The Qualia model tier that read (or reads) the episodes: the one asked
        for, or once the run answered, the one it reports. Empty while a run that
        named none has not answered.
    pipelineRun:
      readOnly: true
      type: string
      description: |-
        The pipeline run that reads the episodes, a UUID; empty until it
        started. The gateway serves its status and settled credits.
    episodeCount:
      readOnly: true
      type: integer
      description: "Episodes planned for the model: linked to a published task."
      format: int32
    unlinkedCount:
      readOnly: true
      type: integer
      description: "Episodes of the selection left out: no published task."
      format: int32
    unreadCount:
      readOnly: true
      type: integer
      description: |-
        Planned episodes the model could not read (no published video, a
        refused call, an invalid answer). Their other issues are left as they
        were. Each gets an open "not checked" issue (code `not_checked`) that
        takes it out of KEPT, as a confident failure does; against a draft
        task, or on an episode a person kept, it is a note. The next VLM
        reading of the episode closes it, whatever its verdict.
      format: int32
    passCount:
      readOnly: true
      type: integer
      description: Findings written, by verdict.
      format: int32
    failCount:
      readOnly: true
      type: integer
      description: "Failing findings: issues at CONFIDENT confidence or more, else notes."
      format: int32
    uncertainCount:
      readOnly: true
      type: integer
      description: "Uncertain findings: notes."
      format: int32
    datasetChecks:
      readOnly: true
      type: array
      items:
        type: string
      description: |-
        accounts/{account}/datasets/{dataset}/checks/{check}: the catalog
        checks a RunDatasetChecks run reads, by category then check id; empty
        for a run of the single VLM check.
    reviewHealth:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.CheckRun_ReviewHealth"
      description: |-
        A graph check run's review health, computed once when its pipeline
        run ended; set once the run succeeded on a template with the
        review_health step.
    unpublishedCount:
      readOnly: true
      type: integer
      description: |-
        Episodes whose proposed labels did not publish. Their findings stand;
        a run above zero is partial.
      format: int32
    unpublishedProposals:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.CheckRun_UnpublishedProposal"
      description: The first 100 of those episodes, each with why.
    unreadEpisodes:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.CheckRun_UnreadEpisode"
      description: |-
        The first 100 episodes counted in `unread_count`, each with why, in
        the order the run planned them.
    notCheckedSummary:
      readOnly: true
      type: string
      description: |-
        One line on a succeeded run that could not read every planned
        episode, e.g. "completed, 4 of 30 episodes not checked"; empty
        otherwise. The run's state stays SUCCEEDED.
  description: The VLM check's run.
qualia.v1.CheckRun_ReviewHealth:
  type: object
  properties:
    available:
      readOnly: true
      type: boolean
      description: |-
        The rules could read this run. When false, `unavailable_code` and
        `unavailable_reason` say why; the numbers, rows, questions and checks
        are unset.
    unavailableCode:
      readOnly: true
      type: string
      description: |-
        Why not: "no_decisions" (no episode read), "no_task_review" (no
        observation was read), "no_task_map" (no upload of the run has a task
        discovery), "map_incomplete" (the map covers under 90% of the run's
        episodes, e.g. after cuts), "partial_run" (the run read under 90% of
        the discovered episodes) or "invalid_input".
    unavailableReason:
      readOnly: true
      type: string
      description: Why not, in a sentence.
    version:
      readOnly: true
      type: string
      description: '"review-health-v1".'
    thresholdsSha256:
      readOnly: true
      type: string
      description: sha256 of the frozen thresholds (CurationBench's THRESHOLDS_SHA256).
    prepareOperations:
      readOnly: true
      type: array
      items:
        type: string
      description: |-
        accounts/{account}/operations/{operation}: the prepare runs whose task
        discovery it read, one per upload.
    episodeCount:
      readOnly: true
      type: integer
      description: Episodes read.
      format: int32
    reviewedCount:
      readOnly: true
      type: integer
      description: Of them, episodes whose observation was read.
      format: int32
    removedCount:
      readOnly: true
      type: integer
      description: Removals.
      format: int32
    removalRate:
      readOnly: true
      type: number
      description: removed_count / episode_count.
      format: double
    mapSucceededCount:
      readOnly: true
      type: integer
      description: Episodes the discovery map calls successful.
      format: int32
    mapSucceededShare:
      readOnly: true
      type: number
      description: map_succeeded_count / episode_count.
      format: double
    gap:
      readOnly: true
      type: number
      description: The kept share less the share the map calls successful.
      format: double
    removedCompletedCount:
      readOnly: true
      type: integer
      description: |-
        Removals whose observation says the task was completed (they
        deviated).
      format: int32
    deviatesCompletedShare:
      readOnly: true
      type: number
      description: removed_completed_count / removed_count.
      format: double
    mapCoverage:
      readOnly: true
      type: number
      description: Share of the run's episodes the map covers.
      format: double
    groupingAgreement:
      readOnly: true
      type: number
      description: |-
        Share of the run's episodes judged against a Task linked to their own
        discovered task.
      format: double
    contradictionChecked:
      readOnly: true
      type: boolean
      description: |-
        The contradiction rule ran: false when grouping_agreement is under
        0.9.
    tasks:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.ReviewHealth_TaskRow"
      description: Per task, largest first.
    questions:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.ReviewHealth_Question"
      description: At most three questions, in the rules' order.
    moreQuestions:
      readOnly: true
      type: array
      items:
        type: string
      description: The rules of questions past the three, not shown.
    spotCheck:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.ReviewHealth_SpotCheck"
      description: The spot check.
    missCheck:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.ReviewHealth_MissCheck"
      description: The miss check; unset unless the run keeps too much.
  description: |-
    Label-free warning signs of a graph check run's removals, read against
    the task discovery of the run's uploads (CurationBench's
    review-health-v1, ported verbatim). Each rule only asks a person:
    nothing here changes a finding, no model is called, and no person's
    decision is read. The thresholds were set on 2-12 saved CurationBench
    runs and are frozen. A take the prepare run cut has no map outcome, so
    it speaks mostly on uploads that were not cut.
qualia.v1.ReviewHealth_TaskRow:
  type: object
  properties:
    task:
      readOnly: true
      type: string
      description: The task's display name in the discovery, else the Task's label.
    episodeCount:
      readOnly: true
      type: integer
      description: Its episodes in the run.
      format: int32
    removedCount:
      readOnly: true
      type: integer
      description: Of them, removals.
      format: int32
    mapSucceededCount:
      readOnly: true
      type: integer
      description: Of them, episodes the discovery map calls successful.
      format: int32
    removalRate:
      readOnly: true
      type: number
      description: removed_count / episode_count.
      format: double
    mapSucceededShare:
      readOnly: true
      type: number
      description: map_succeeded_count / episode_count.
      format: double
    gap:
      readOnly: true
      type: number
      description: The kept share less the share the map calls successful.
      format: double
  description: One task's numbers.
qualia.v1.ReviewHealth_Question:
  type: object
  properties:
    rule:
      readOnly: true
      type: string
      description: |-
        The rule that asks it: "contradiction" (tasks may be mixed),
        "under_removal", "over_removal" or "outcome_data".
    question:
      readOnly: true
      type: string
      description: The question, in a sentence.
    detail:
      readOnly: true
      type: string
      description: Why it is asked, with the numbers.
    groups:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.ReviewHealth_Group"
      description: "contradiction: the tasks it fires on."
    episodes:
      readOnly: true
      type: array
      items:
        type: string
      description: Example episodes.
    action:
      readOnly: true
      type: string
      description: |-
        Where it is answered: "tasks" (the task grouping and the
        references), "miss_check" (the miss check below), or empty.
  description: One question for a person, with example episodes.
qualia.v1.ReviewHealth_Group:
  type: object
  properties:
    task:
      readOnly: true
      type: string
      description: The task's display name in the discovery.
    variant:
      readOnly: true
      type: string
      description: The variant's name; empty for a whole task.
    episodeCount:
      readOnly: true
      type: integer
      description: Its episodes in the run.
      format: int32
    removedCount:
      readOnly: true
      type: integer
      description: "Of them, removals: a failing finding."
      format: int32
    mapSucceededCount:
      readOnly: true
      type: integer
      description: Of them, episodes the discovery map calls successful.
      format: int32
    referenceEpisodeIds:
      readOnly: true
      type: array
      items:
        type: string
      description: |-
        The SUCCESS references most of them were judged against, by episode
        id: a Task's reference can live in another dataset.
  description: A task (or variant) the contradiction rule fires on.
qualia.v1.ReviewHealth_SpotCheck:
  type: object
  properties:
    episodes:
      readOnly: true
      type: array
      items:
        type: string
      description: The episodes, at most ten, picked reproducibly from the pool.
    poolCount:
      readOnly: true
      type: integer
      description: Every removal the map calls successful.
      format: int32
    flagErrorCount:
      readOnly: true
      type: integer
      description: |-
        Wrong removals among the episodes that say the references or the
        Task may not fit the dataset (4).
      format: int32
  description: |-
    Removals the discovery map calls successful, for a person to open:
    keeping one says the run was wrong to remove it.
qualia.v1.ReviewHealth_MissCheck:
  type: object
  properties:
    episodes:
      readOnly: true
      type: array
      items:
        type: string
      description: The episodes shown, at most eight.
    restEpisodes:
      readOnly: true
      type: array
      items:
        type: string
      description: The rest of the queue, in removal-score order.
    poolCount:
      readOnly: true
      type: integer
      description: The whole queue.
      format: int32
    confirmCount:
      readOnly: true
      type: integer
      description: |-
        Removals among the shown episodes that say the rest likely go too
        (5).
      format: int32
  description: |-
    Kept episodes that rank next for removal, when the run keeps more
    than the map calls successful.
qualia.v1.CheckRun_UnpublishedProposal:
  type: object
  properties:
    episode:
      readOnly: true
      type: string
      description: accounts/{account}/datasets/{dataset}/episodes/{episode}
    reason:
      readOnly: true
      type: string
      description: Why, as the publisher answered.
    pending:
      readOnly: true
      type: boolean
      description: |-
        Nobody saw the publication end: it may still land. Running the same
        reading again replays it.
  description: An episode whose proposed labels did not publish.
qualia.v1.CheckRun_UnreadEpisode:
  type: object
  properties:
    episode:
      readOnly: true
      type: string
      description: accounts/{account}/datasets/{dataset}/episodes/{episode}
    reason:
      readOnly: true
      type: string
      description: |-
        Why, in a sentence: no published video, a refused call, an invalid
        answer.
  description: A planned episode the run could not read.
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.
```