# Versions_ListVersionPreviewItems

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

A preview's windows, take by take, with what each measured: the
numbers its charts draw. Paged.

- 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.
- `pageSize` (query, integer (int32)): At most this many windows; 0 means 500, the maximum is 2000.
- `pageToken` (query, string): From a previous response's next_page_token.

## Responses

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

## Schemas

```yaml
qualia.v1.ListVersionPreviewItemsResponse:
  type: object
  properties:
    versionPreviewItems:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.VersionPreviewItem"
      description: One page of windows, in take order and each take's in time order.
    nextPageToken:
      type: string
      description: Empty on the last page.
  description: Response for Versions.ListVersionPreviewItems.
qualia.v1.VersionPreviewItem:
  type: object
  properties:
    take:
      readOnly: true
      type: string
      description: |-
        accounts/{account}/datasets/{dataset}/episodes/{episode}: the take it
        is cut from.
    piece:
      readOnly: true
      type: integer
      description: Its place among the take's windows, from 0.
      format: int32
    pieces:
      readOnly: true
      type: integer
      description: "The take's windows: 1 for a take as recorded or trimmed, more for a split."
      format: int32
    startSeconds:
      readOnly: true
      type: number
      description: Where it starts, seconds from the start of the take's recording.
      format: double
    endSeconds:
      readOnly: true
      type: number
      description: Where it ends, seconds from the start of the take's recording.
      format: double
    label:
      readOnly: true
      type: string
      description: |-
        The take as a person finds it in the dataset, e.g. "episode 41 ·
        pick_cup_041".
    episode:
      readOnly: true
      type: string
      description: |-
        accounts/{account}/datasets/{dataset}/episodes/{episode}: the episode
        the version pins for it. The take itself when it is published as
        recorded; for an edited take, its new episode once the preview is
        PUBLISHED, and empty before (publishing makes the new episodes).
    analysis:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Episode_Analysis"
      description: |-
        How it moves, measured over the window alone, as Episode.analysis
        reads; unset when it could not be measured.
  description: |-
    One window of a preview: a stretch of one take the version would hold,
    and how it measured.
qualia.v1.Episode_Analysis:
  type: object
  properties:
    version:
      readOnly: true
      type: string
      description: |-
        The definition the numbers follow; a reader treats another one as
        not measured yet.
    unmeasuredReason:
      readOnly: true
      type: string
      description: |-
        Why the take could not be measured: "no_joints" (no state) or
        "channel_never_read". Empty when measured.
    fps:
      readOnly: true
      type: number
      description: Rows per second it was measured at.
      format: double
    frames:
      readOnly: true
      type: integer
      description: Rows read.
      format: int32
    speedVariance:
      readOnly: true
      type: number
      description: Variance of the joint speed over every state channel, (units/s)^2.
      format: double
    speedMean:
      readOnly: true
      type: number
      description: Mean joint speed over every state channel, units/s.
      format: double
    jerkMean:
      readOnly: true
      type: number
      description: Mean norm of the state's third difference, units/s^3.
      format: double
    highFrequencyRatio:
      readOnly: true
      type: number
      description: Share of the speed spectrum's power above 3 Hz.
      format: double
    idleRatio:
      readOnly: true
      type: number
      description: Share of frames under 5% of the top speed.
      format: double
    tremble:
      readOnly: true
      type: number
      description: Mean |v_smooth - v| / (|v_smooth| + |v|) over the arm joints.
      format: double
    gripperEventCount:
      readOnly: true
      type: integer
      description: Commanded gripper moves of at least 30% of their travel.
      format: int32
    gripperFlickerCount:
      readOnly: true
      type: integer
      description: The most events of one gripper inside 0.5 s.
      format: int32
    correctionCount:
      readOnly: true
      type: integer
      description: Regrasps within 3 s, plus events the arm retraces its approach round.
      format: int32
    stateChannels:
      readOnly: true
      type: array
      items:
        type: string
      description: State channel names, in the order of the poses.
    startPose:
      readOnly: true
      type: array
      items:
        type: number
        format: double
      description: First state row, every channel.
    endPose:
      readOnly: true
      type: array
      items:
        type: number
        format: double
      description: Last state row, every channel.
    channels:
      readOnly: true
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.Analysis_Channel"
      description: Every commanded channel, in recording order.
  description: |-
    How the take moves, as the dataset page's outliers and training tabs
    read it: measured once from its series, within a few
    minutes of a publish, and again only when its data changes (a re-ingest,
    or a trim or a split, measured as it is applied); a ruling or a tag
    measures nothing. The set's fences, embedding and chart averages are
    laid out over these by the reader.
    Read in the EPISODE_VIEW_ANALYSIS view of ListEpisodes (each channel's
    progress only) and of GetEpisode (with the curves); unset when the take
    is not measured yet, or its profile measured another revision of it
    than the one the listed scope reads (before a trim, a re-ingest or a
    split; or through a mixture pinned to an earlier revision, which is
    not measured: only uploads' current members are). The definitions are dataset-ux-proto's
    (scripts/extract.py, src/lib/mock): they differ on purpose from the
    like-named Metrics, which are command-space and feed curation.
qualia.v1.Analysis_Channel:
  type: object
  properties:
    name:
      readOnly: true
      type: string
      description: Channel name, as the recording names it.
    progress:
      readOnly: true
      type: array
      items:
        type: number
        format: double
      description: The value at 50 evenly spaced points of the take, first to last.
    autocorrelation:
      readOnly: true
      type: array
      items:
        type: number
        format: double
      description: |-
        Autocorrelation at lags 1..min(100, frames / 2); empty when the
        channel never moves, and in a list.
    alignment:
      readOnly: true
      allOf:
        - $ref: "#/components/schemas/qualia.v1.Channel_Alignment"
      description: Unset when the state has no channel of this name, and in a list.
  description: One commanded channel's training-chart inputs.
qualia.v1.Channel_Alignment:
  type: object
  properties:
    correlation:
      readOnly: true
      type: array
      items:
        type: number
        format: double
      description: |-
        Correlation at lags -30..30 frames; NaN where a lag has no
        variance. Empty when the take is under 5 frames.
  description: Cross-correlation of the channel's step against its measured twin's.
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.
```