# Episodes_SampleEpisodeSeries

`GET /v1/accounts/{account}/datasets/{dataset}/episodes/{episode}:sampleSeries`

The episode's joint series: each state and action channel sampled evenly
over the take's current content: the joints drawer's charts, and the
arm's motion the camera lag drawer sets each camera's offset against.
Its window says where those samples sit in the episode's recording.
A handheld take resolved at its TCP also has the hands' TCP poses, when
streams names TCP.
A take in no published version yet answers unpublished, with no
channels; FAILED_PRECONDITION means the published content cannot be
sampled (a column type it cannot read, say).

- 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.
- `episode` (path, string, required): The episode id.
- `maxPoints` (query, integer (int32)): Samples to return at most, 2 to 2000; 400 when unset. A take with fewer
  frames returns every frame. The first and last frame are always samples.
- `streams` (query, array of string (enum)): The vectors to sample, each at most once; STATE and ACTION when empty
  (TCP only when named). A take whose action cannot be read still answers
  for its state alone, and one with no TCP (not a handheld take resolved at
  its TCP) answers for the rest without it.

  ```yaml
  type: array
  items:
    enum:
      - STREAM_UNSPECIFIED
      - STATE
      - ACTION
      - TCP
    type: string
    format: enum
  ```
- `version` (query, string): Read as this version froze it: a tag, `stable`, `v0` or a
  digest prefix; empty or `head` reads the episode as it is now. As
  GetEpisodeRequest.version: the series of the member that version holds.

## Responses

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

## Schemas

```yaml
qualia.v1.SampleEpisodeSeriesResponse:
  type: object
  properties:
    timeSeconds:
      type: array
      items:
        type: number
        format: double
      description: |-
        Seconds from the first frame sampled, one per sample: a sample's second
        of the episode's recording is this plus window_start_seconds.
    channels:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.SampleEpisodeSeriesResponse_Channel"
      description: Every channel the recording carries, on time_seconds.
    fps:
      type: number
      description: The recording's frames per second.
      format: double
    frameCount:
      type: string
      description: "Frames sampled: the take's, or what its applied trim keeps."
    unpublished:
      type: boolean
      description: |-
        True when the take is in no published version yet (a split child
        before its publish): it has no channels to sample.
    windowStartSeconds:
      type: number
      description: |-
        Where the first frame sampled sits in the episode's recording, in
        seconds of the recording (the clock its trim, subtasks and markers are
        in), on that frame: 0 until a trim is applied, the trim's start once one
        is; a split's piece is a recording of its own, so 0. Unset with
        unpublished.
      format: double
    windowEndSeconds:
      type: number
      description: |-
        Where the frames sampled end in the recording, in the same seconds: the
        end of the last one (window_start_seconds plus frame_count / fps).
        Unset with unpublished.
      format: double
  description: Response for Episodes.SampleEpisodeSeries.
qualia.v1.SampleEpisodeSeriesResponse_Channel:
  type: object
  properties:
    stream:
      enum:
        - STREAM_UNSPECIFIED
        - STATE
        - ACTION
        - TCP
      type: string
      description: Which vector.
      format: enum
    key:
      type: string
      description: |-
        Its positional key, "state[3]" or "action[3]"; the dataset's robot
        interface names the positions. A TCP channel is named, "left.tcp.x".
    values:
      type: array
      items:
        type: number
        format: double
      description: One value per sample; 0 where valid is false.
    valid:
      type: array
      items:
        type: boolean
      description: "Per sample: false where the recording holds no finite value."
  description: "One channel: one component of the state or the action vector."
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.
```