# Checks_RunDatasetChecks `POST /v1/accounts/{account}/datasets/{dataset}/checks:run` Runs catalog checks over a dataset as one run: the union of `check_ids`, `categories` and `all`, deduplicated, on the episodes of `selection`, sampled to `max_episodes`. The selection is resolved and pinned before the estimate (check versions, Task revisions, episodes), and the run reads exactly what was pinned. One model call per episode reads every selected VLM check. An episode a check cannot read (no published Task for a Task check) is skipped for that check, never passed. `all` and a category take the checks that can run and list the rest in `skipped_checks`. INVALID_ARGUMENT, before anything starts, for an empty selection, an unknown check id or category, a named check that cannot run on this dataset, a selection none of whose checks can run, or when no episode is eligible for any selected check; FAILED_PRECONDITION on a deployment with no checks runner, and, for a person's run, while a selected check is still running on this dataset: the message names that run, which DatasetCheck.running_check_run also lists. An estimate (`validate_only`) is answered either way. A retry with the first call's request_id is answered with its run, not refused. With `validate_only` nothing starts and nothing is reserved: the response carries the resolved selection and pipeline-api's bound for it, the same bound a run reserves. A run needs `max_cost` at or above that bound. Each run is a CheckRun under `checks/vlm`. - 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. ## Request body Required: `application/json` `qualia.v1.RunDatasetChecksRequest` ## Responses - `200` OK: `application/json` `qualia.v1.RunDatasetChecksResponse` - `default` Default error response: `application/json` `google.rpc.Status` ## Schemas ```yaml qualia.v1.RunDatasetChecksRequest: required: - dataset type: object properties: dataset: type: string description: accounts/{account}/datasets/{dataset} checkIds: type: array items: type: string description: Check ids to run, e.g. `task.graph`. categories: type: array items: type: string description: Categories to run every runnable check of the selected kind. all: type: boolean description: Run every runnable check of the selected kind. selection: allOf: - $ref: "#/components/schemas/qualia.v1.EpisodeSelection" description: |- Only these episodes (names under `dataset`, or a ListEpisodes filter); unset means all. maxEpisodes: type: integer description: |- Sample at most this many eligible episodes, evenly spread and the same for the same request. Must be positive; unset reads all of them. format: int32 maxCost: type: string description: |- The most credits the run may reserve and spend. Required to start a VLM run, and must cover the bound; optional with `validate_only`. Heuristic runs have a bound of zero and do not require max_cost. validateOnly: type: boolean description: |- Resolve the selection and answer the bound, starting and reserving nothing. model: type: string description: |- The Qualia model tier that reads the VLM checks, one of CheckEstimate.models; a legacy vendor model id is still accepted. Empty: the runner's default. requestId: type: string description: |- Idempotency key (AIP-155): a retry with the same id within 24 hours returns the first call's run and its pinned selection instead of starting a second one. Required to start a run. kind: enum: - KIND_UNSPECIFIED - VLM - HEURISTIC type: string description: |- Kind selected by all and categories. Unset: the kind `check_ids` names; else VLM when a VLM check they reach can run here, else heuristic. A run reads one kind; the checks it leaves out are listed in `skipped_checks`. Explicit check_ids may name either kind, but cannot mix kinds in one run. format: enum description: Request for Checks.RunDatasetChecks. qualia.v1.EpisodeSelection: type: object properties: names: allOf: - $ref: "#/components/schemas/qualia.v1.EpisodeNames" description: Episode names under the request's parent. filter: type: string description: A ListEpisodes filter over the parent (e.g. what the filter bar leaves). description: |- Which episodes a bulk ruling acts on: an explicit list, or a filter. Names must be under the request's parent (INVALID_ARGUMENT otherwise); a filter only ever matches the parent's own episodes (a mixture: its pool). qualia.v1.EpisodeNames: type: object properties: names: type: array items: type: string description: accounts/{account}/datasets/{dataset}/episodes/{episode}, at most 10000. description: A list of episode names. qualia.v1.RunDatasetChecksResponse: type: object properties: checks: type: array items: $ref: "#/components/schemas/qualia.v1.DatasetCheckSelection" description: The resolved checks, by category then check id. episodeCount: type: integer description: "Episodes selected: after the selection and sample cap." format: int32 skippedCount: type: integer description: Episodes of the selection that no selected check can read. format: int32 estimate: allOf: - $ref: "#/components/schemas/qualia.v1.CheckEstimate" description: "What the run reserves: pipeline-api's bound for the pinned selection." checkRun: type: string description: |- accounts/{account}/checks/vlm/runs/{run}: the run; empty with `validate_only`. skippedChecks: type: array items: $ref: "#/components/schemas/qualia.v1.SkippedDatasetCheck" description: |- Checks `all` or `categories` reached that the run leaves out, by category then check id, with why. An id in `check_ids` that cannot run is refused instead. The VLM check's own steps (graph.observe, graph.evaluate) run only inside it and are left out unlisted. description: Response for Checks.RunDatasetChecks. qualia.v1.DatasetCheckSelection: type: object properties: datasetCheck: type: string description: accounts/{account}/datasets/{dataset}/checks/{check} version: type: integer description: The check version pinned. format: int32 kind: enum: - KIND_UNSPECIFIED - VLM - HEURISTIC type: string description: How it reads an episode. format: enum episodeCount: type: integer description: Selected episodes it will read. format: int32 skippedCount: type: integer description: Selected episodes it skips, with `skip_reason`. format: int32 skipReason: type: string description: Why it skips them (e.g. no published Task); empty when it skips none. description: One selected check, as the run pins it. qualia.v1.CheckEstimate: type: object properties: credits: readOnly: true type: string description: |- Credits the run would reserve: on a merged dataset, the sum over its uploads' runs. episodeCount: readOnly: true type: integer description: |- Episodes the model would read: linked to a published task, in a published version, with a camera. format: int32 unlinkedCount: readOnly: true type: integer description: |- Episodes of the selection it would leave out: not linked to a task, linked to one with no published revision, not in a published version, or without a camera. format: int32 model: readOnly: true type: string description: |- The Qualia model tier it would read with ("qualia-vlm-fast"): the request's, else the template's default. models: readOnly: true type: array items: type: string description: |- Every Qualia model tier this deployment's VLM check offers, the default first. A request may still name a legacy vendor model id (deprecated). description: |- What a VLM check run would read and the credits it would reserve, before it starts (RunCheck with validate_only). Nothing is reserved or charged by asking. A run reserves when it starts, sized the same way on the episodes it can read then; its charge is the calls it made, never more than its reservation, and a failed run is refunded. qualia.v1.SkippedDatasetCheck: type: object properties: datasetCheck: type: string description: accounts/{account}/datasets/{dataset}/checks/{check} version: type: integer description: Its active version. format: int32 kind: enum: - KIND_UNSPECIFIED - VLM - HEURISTIC type: string description: How it reads an episode. format: enum reason: type: string description: |- Why the run leaves it out: it cannot run here, or it is of the other kind and runs as its own run. description: A check the selection reached that the run leaves out. 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. ```