# Checks_GetReachStatus

`GET /v1/accounts/{account}/datasets/{dataset}/reachStatus`

Where a dataset's reach check stands: the settings a RunCheck would use
now, the key they make, and the dataset's runs. A merged dataset pressed
before its press was one run holds that press in its uploads,
one run each: until it has a run of its own (and a finished one), that
press reads as one run, its counts summed, RUNNING while any part runs
(REQUESTED while one waits), else FAILED with a failed part's note, else
SUCCEEDED, its operation its first part's. Runs made before an upload
joined this merged dataset are excluded. Writes nothing. 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.
- `dataset` (path, string, required): The dataset id.

## Responses

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

## Schemas

```yaml
qualia.v1.ReachStatus:
  type: object
  properties:
    name:
      type: string
      description: accounts/{account}/datasets/{dataset}/reachStatus
    settings:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.ReachSettings"
      description: |-
        The settings a RunCheck on `checks/reach` would use now, resolved: the
        target robot's solver, and the dataset's base and heading, else the robot
        model's reach_base, else 0, 0, 0. A dataset has no solver of its own, and
        there is no default solver: `solver` is SOLVER_UNSPECIFIED whenever none
        was resolved (no target robot, the robot removed, without a model or in
        another workspace, a robot without a solver, or fleet could not be
        asked).
    currentKey:
      readOnly: true
      type: string
      description: |-
        The reach key those settings make with the target robot's current model
        config. Empty when the dataset has no target robot, the robot cannot be
        solved against (removed, no model, no solver, in another workspace), a
        merged dataset's uploads hold their poses at different frames, or fleet
        could not be asked.
    lastRun:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.ReachRun"
      description: The newest run of any state; unset until the first press.
    lastFinishedRun:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.ReachRun"
      description: |-
        The newest run that ended (SUCCEEDED, FAILED or CANCELLED); unset until
        one has.
    stale:
      readOnly: true
      type: boolean
      description: |-
        Whether last_run was made under another key than current_key: the
        target robot, model, placement, pose frame or calibration changed since,
        and a RunCheck would compute something new. Nothing runs by itself.
    targetRobot:
      readOnly: true
      type: string
      description: accounts/{account}/robots/{robot}; empty if no target robot is assigned.
  description: |-
    Where a dataset's reach check stands (Checks.GetReachStatus): one per
    dataset, always there. Reading it writes nothing and asks for no run.

    Served by qds-api.
qualia.v1.ReachSettings:
  type: object
  properties:
    solver:
      enum:
        - SOLVER_UNSPECIFIED
        - PYROKI
        - DLS
        - MINK
      type: string
      description: |-
        The IK solver the dataset is solved with: always its target robot's, and
        set only on a status read (a run's resolved settings). A dataset does not
        pick one: a request that names a solver here (UpdateDataset, CreateDataset)
        is refused with INVALID_ARGUMENT ("a dataset uses its robot's solver;
        change it on the robot's Solver page"), and a solver stored on a dataset
        before that is ignored. A robot with no solver cannot be solved on.
      format: enum
    baseM:
      type: array
      items:
        type: number
        format: double
      description: |-
        Where the takes' start sits from the relaxed grippers' midpoint, metres
        in the robot's base frame (x forward, y left, z up): empty or exactly
        three numbers, each finite and within 5 m either way. Empty follows the
        target robot model's `reach_base`, else 0, 0, 0. Stored to 0.1 mm and
        applied to both hand paths as one rigid translation from the robot's home
        hand midpoint.
    homeHeadingRad:
      type: number
      description: |-
        Rotate both paired paths around world up before placing their first-row
        midpoint at the shared home reference. Radians; finite and within +/- pi.
        The robot base remains at world (0, 0, 0).
      format: double
    poseSource:
      readOnly: true
      enum:
        - POSES_AT_UNSPECIFIED
        - ROOT
        - TCP
      type: string
      description: |-
        Where the source episode's hand poses were recorded. Set by qds-api on
        reads; clients do not set it. TCP runs consume already-resolved TCP
        channels and never apply calibration again.
      format: enum
    calibrationDigest:
      readOnly: true
      type: string
      description: |-
        Digest of the TCP calibration already applied to the published upload,
        empty for root poses. Set by qds-api on reads.
  description: |-
    How a dataset's reach check is walked: where the takes
    start and which way they face. It is stored on the dataset, so two datasets
    over one robot keep their own, and it is part of the key a reach result is
    stored under: a result is shared by every dataset that asks the same
    question (same robot config, solver, base and walk), and a change here
    leaves the old results as they are until the next RunCheck on
    `checks/reach`. The solver is not a dataset's to choose: a dataset uses its
    robot's, tuned in the robot's solver file.

    Served by qds-api.
qualia.v1.ReachRun:
  type: object
  properties:
    operation:
      readOnly: true
      type: string
      description: "accounts/{account}/operations/{operation}: the RunCheck that recorded it."
    key:
      readOnly: true
      type: string
      description: The key its results are stored under (ReachStatus.current_key).
    settings:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.ReachSettings"
      description: |-
        What it was keyed with, resolved: the solver is PYROKI, DLS or MINK and base_m
        has three numbers.
    robot:
      readOnly: true
      type: string
      description: "accounts/{account}/robots/{robot}: the target robot it ran on."
    requestTime:
      readOnly: true
      type: string
      description: When Run solver was pressed.
      format: date-time
    state:
      readOnly: true
      enum:
        - STATE_UNSPECIFIED
        - REQUESTED
        - RUNNING
        - SUCCEEDED
        - FAILED
        - CANCELLED
      type: string
      description: Where it stands.
      format: enum
    total:
      readOnly: true
      type: integer
      description: |-
        The takes it covers (handheld and egocentric episodes that carry hand
        poses): those of the dataset when it was pressed
        (or the selection), the ones answered from stored results included.
      format: int32
    done:
      readOnly: true
      type: integer
      description: Takes with a result.
      format: int32
    failed:
      readOnly: true
      type: integer
      description: Takes that could not be solved.
      format: int32
    note:
      readOnly: true
      type: string
      description: |-
        Why a run that stands REQUESTED or RUNNING has not moved, or why it was
        given up, in a sentence a person reads ("waiting for the reach service",
        "some takes are not ready yet", "the robot model changed; run again").
        Empty while it is moving.
  description: |-
    One press of Run solver: a RunCheck on `checks/reach`, as the dataset
    recorded it.
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.
```