# Versions_GetVersionPreview

`GET /v1/accounts/{account}/datasets/{dataset}/versionPreviews/{versionPreview}`

Gets a preview: how far it is, its counts, and, once READY, how it
compares with the newest tag and what changed since it was made.

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

## Responses

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

## Schemas

```yaml
qualia.v1.VersionPreview:
  type: object
  properties:
    name:
      type: string
      description: accounts/{account}/datasets/{dataset}/versionPreviews/{version_preview}
    include:
      readOnly: true
      type: array
      items:
        enum:
          - CLASS_UNSPECIFIED
          - KEPT_BY_PERSON
          - KEPT
          - FLAGGED
          - REJECTED
          - REJECTED_BY_PERSON
        type: string
        format: enum
      description: Which takes it took, by how they stood when it was made.
    state:
      readOnly: true
      enum:
        - STATE_UNSPECIFIED
        - MEASURING
        - READY
        - PUBLISHING
        - PUBLISHED
        - FAILED
        - DISCARDED
        - SUPERSEDED
        - EXPIRED
      type: string
      description: Where it is.
      format: enum
    measuredWindowCount:
      readOnly: true
      type: string
      description: |-
        Windows measured so far, of `window_count`. A window is one stretch of
        one take the version would hold: the take as recorded, its trim, or one
        piece of its split.
    windowCount:
      readOnly: true
      type: string
      description: Windows to measure.
    episodeCount:
      readOnly: true
      type: string
      description: |-
        Episodes the version would pin: each take it has as recorded, and each
        new episode an edited take becomes.
    durationSeconds:
      readOnly: true
      type: number
      description: Recorded time those episodes span, seconds.
      format: double
    editedCount:
      readOnly: true
      type: string
      description: Takes the version would publish with the edit drawn on them.
    trimmedCount:
      readOnly: true
      type: string
      description: Edited takes that become one new episode (a trim, new subtasks or both).
    splitCount:
      readOnly: true
      type: string
      description: Edited takes that become two or more new episodes.
    pieceCount:
      readOnly: true
      type: string
      description: New episodes the edited takes become, across every edited take.
    includedFlaggedCount:
      readOnly: true
      type: string
      description: Episodes it would pin that stand FLAGGED.
    includedRejectedCount:
      readOnly: true
      type: string
      description: Episodes it would pin that stand REJECTED.
    unmeasuredCount:
      readOnly: true
      type: string
      description: |-
        Windows with nothing in them to measure. Their episodes are still in
        the version; the preview's charts leave them out.
    unprofiledCount:
      readOnly: true
      type: string
      description: |-
        Takes with no profile of the recording as it was taken: the layer the
        preview's charts draw behind the version's leaves them out.
    unprocessable:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.VersionPreview_Unprocessable"
      description: "Takes it leaves out, and why: the version will not have them."
    changedCount:
      readOnly: true
      type: string
      description: |-
        Takes it took whose ruling, drawing, labels or recording changed since
        it was made. Publishing it still publishes them as previewed. Counted
        only while READY; 0 otherwise.
    versus:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.VersionPreview_Versus"
      description: |-
        How it compares with the dataset's newest tag; unset when there is none.
        Set while READY and on a validate_only response. Validation reads both
        selections in one read-only snapshot. To count changes since a particular
        newest preview-made tag, validate with that tag's include and check this
        tag still matches; retry the newest-tag read if it changed.
    sameAsVersion:
      readOnly: true
      type: string
      description: |-
        A tag ("1.2") holding exactly the episodes it would pin, if there is
        one: publishing it would make that tag again. Empty otherwise, and until
        it is READY.
    version:
      readOnly: true
      type: string
      description: |-
        accounts/{account}/datasets/{dataset}/versions/{version}: the tag it
        was published as, once PUBLISHED.
    publishError:
      readOnly: true
      type: string
      description: |-
        Why it cannot be published as it stands (a merged dataset whose uploads
        freeze different training contracts), or why the last
        PublishVersionPreview stopped short of a tag, naming the takes. Empty
        when nothing stands in the way.
    creator:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Actor"
      description: |-
        Who made it, a person or an API key: its owner, the only caller who
        publishes or discards it.
    createTime:
      readOnly: true
      type: string
      description: When it was made.
      format: date-time
    updateTime:
      readOnly: true
      type: string
      description: When it last changed.
      format: date-time
    readyTime:
      readOnly: true
      type: string
      description: When it became READY; unset before.
      format: date-time
    expireTime:
      readOnly: true
      type: string
      description: When it EXPIRES unless it is published first.
      format: date-time
    draftsUnpublishedCount:
      readOnly: true
      type: string
      description: |-
        Takes of the dataset with an edit drawn that no tag has published yet,
        whether the preview took them or not.
  description: |-
    What a version would be: the dataset's takes as they stand now, picked by
    how they stand (`include`), each with the edit drawn on it (its draft)
    cut out of the recorded bytes and measured, before anything is published
    ("Apply all" in the Create version dialog). Making one writes nothing a
    dataset reads: head, its episodes, their standing, their profiles and
    every draft stay as they are. PublishVersionPreview turns it into a tag:
    each edited take is cut into new episodes beside the take, and the tag
    pins exactly the takes and windows the preview froze, however they have
    changed since (`changed_count` says how many have).

    A caller has at most one live preview of a dataset (MEASURING, READY,
    PUBLISHING or FAILED): a new CreateVersionPreview supersedes the caller's
    earlier one when it is MEASURING, READY or FAILED, and is refused
    (FAILED_PRECONDITION) while it is PUBLISHING, which only its publish ends.
    Uploads and merged datasets have them; a mixture is tagged from head
    (CreateVersion).

    The {version_preview} id is a UUID.

    Served by qds-api.
qualia.v1.VersionPreview_Unprocessable:
  type: object
  properties:
    episode:
      readOnly: true
      type: string
      description: "accounts/{account}/datasets/{dataset}/episodes/{episode}: the take."
    label:
      readOnly: true
      type: string
      description: |-
        The take as a person finds it in the dataset, e.g. "episode 41 ·
        pick_cup_041".
    reasonCode:
      readOnly: true
      type: string
      description: |-
        Why, as a stable UPPER_SNAKE_CASE code to branch on: KEEPS_NOTHING
        (the drawing keeps no frame), TOO_MANY_PIECES (more than 512),
        ALREADY_SPLIT (drawn on a take split before), A_PIECE (drawn on a
        piece of one), UNMEASURABLE (its windows failed to measure three
        times), and others to come.
    reason:
      readOnly: true
      type: string
      description: "Why, in a person's words: \"the drawing keeps nothing\"."
  description: A take the preview leaves out, and why.
qualia.v1.VersionPreview_Versus:
  type: object
  properties:
    tag:
      readOnly: true
      type: string
      description: The newest tag ("1.2").
    addedCount:
      readOnly: true
      type: string
      description: Episodes the preview has and the tag does not.
    removedCount:
      readOnly: true
      type: string
      description: Episodes the tag has and the preview does not.
    changedCount:
      readOnly: true
      type: string
      description: Takes in both, at another revision or with another edit.
    unchangedCount:
      readOnly: true
      type: string
      description: Episodes in both, the same.
  description: |-
    How the preview's episodes compare with the dataset's newest tag. An
    edited take matches a tag's new episodes when they were cut from the
    same recording with the same drawing.
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.
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.
```