# Explore the episode lake: one page + totals + facet counts

`POST /v1/datasets/explore`

The account's episode lake as ONE unit (one-lake IA): a page of
episodes across every source dataset, with metadata filters (task, tier,
embodiment via ``interface_hash``, tags, review state, source datasets)
plus filtered totals and standard facet counts — one broker call, one
qds-api RPC, never a per-dataset fan-out.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header, or `Authorization: Bearer …`

## Parameters

- `account_id` (query, string | null (uuid)): Act on this account (active)

## Request body

Required: `application/json` `ExploreLakeBody`

## Responses

- `200` One internally consistent live-MVCC page, filtered totals, bounded self-excluding facets with full cardinalities, and independently checkable channel-predicate evidence: `application/json` `ExploreLakeResponseModel`
- `400` QDS data plane not enabled
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `422` Validation Error: `application/json` `HTTPValidationError`

## Schemas

```yaml
ExploreLakeBody:
  properties:
    tasks:
      items:
        type: string
      type: array
      maxItems: 512
    tiers:
      items:
        type: string
        enum:
          - ""
          - retrainable
          - analyze_only
      type: array
      maxItems: 512
    interface_hashes:
      items:
        type: string
      type: array
      maxItems: 512
    tags:
      items:
        type: string
      type: array
      maxItems: 512
    marker_signatures:
      items:
        type: string
      type: array
      maxItems: 512
    review_state:
      type: string
      enum:
        - ""
        - unreviewed
        - auto_accepted
        - human_audited
        - rejected
      default: ""
    dataset_ids:
      items:
        type: string
        format: uuid
      type: array
      maxItems: 4096
    episode_index:
      maximum: 2147483647
      minimum: 0
      type:
        - integer
        - "null"
    lineage:
      type: string
      enum:
        - ""
        - originals
        - children
      default: ""
    parent_episode_index:
      maximum: 2147483647
      minimum: 0
      type:
        - integer
        - "null"
    order_desc:
      type: boolean
      default: false
    limit:
      type: integer
      maximum: 200
      minimum: 1
      default: 50
    offset:
      type: integer
      maximum: 4294967295
      minimum: 0
      default: 0
    search:
      type: string
      default: ""
    numeric_predicates:
      items:
        $ref: "#/components/schemas/NumericPredicateBody"
      type: array
      maxItems: 32
    channel_predicates:
      items:
        $ref: "#/components/schemas/ChannelPredicateBody"
      type: array
      maxItems: 32
  additionalProperties: false
  type: object
  title: ExploreLakeBody
NumericPredicateBody:
  properties:
    field:
      type: string
      enum:
        - duration_s
        - frame_count
        - quality_score
        - speed_mean
        - jerk_mean
        - frozen_action_dims
        - action_dims
        - frozen_state_dims
        - state_dims
        - sync_skew_max_ms
        - sync_skew_ratio
        - sparc
        - ldlj
        - psd_hf_ratio
        - speed_p10
        - speed_p50
        - speed_p90
        - pause_fraction
        - pause_count
        - dt_jitter_ms
        - dt_dropped_frames
    op:
      type: string
      enum:
        - gt
        - lt
        - gte
        - lte
    value:
      type: number
  additionalProperties: false
  type: object
  required:
    - field
    - op
    - value
  title: NumericPredicateBody
ChannelPredicateBody:
  properties:
    stream:
      type: string
      enum:
        - action
        - state
        - telemetry
      default: action
    channel:
      type: string
    agg:
      type: string
      enum:
        - max
        - min
        - mean
        - std
    op:
      type: string
      enum:
        - gt
        - lt
        - gte
        - lte
    value:
      type: number
  additionalProperties: false
  type: object
  required:
    - channel
    - agg
    - op
    - value
  title: ChannelPredicateBody
ExploreLakeResponseModel:
  properties:
    episodes:
      items:
        $ref: "#/components/schemas/LakeEpisodeModel"
      type: array
      maxItems: 200
    total:
      type: integer
      maximum: 18446744073709552000
      minimum: 0
    total_frames:
      type: integer
      maximum: 18446744073709552000
      minimum: 0
    total_duration_seconds:
      type: number
      minimum: 0
    facets:
      $ref: "#/components/schemas/LakeFacetsModel"
    page_limit:
      type: integer
      maximum: 200
      minimum: 1
    page_offset:
      type: integer
      maximum: 4294967295
      minimum: 0
  additionalProperties: false
  type: object
  required:
    - episodes
    - total
    - total_frames
    - total_duration_seconds
    - facets
    - page_limit
    - page_offset
  title: ExploreLakeResponseModel
LakeEpisodeModel:
  properties:
    episode_id:
      type: string
      format: uuid
    dataset_id:
      type: string
      format: uuid
    dataset_name:
      type: string
      maxLength: 128
      minLength: 1
      pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$
    episode_index:
      type: integer
      maximum: 4294967295
      minimum: 0
    task:
      maxLength: 262144
      type:
        - string
        - "null"
    tier:
      nullable: true
      type: string
      enum:
        - retrainable
        - analyze_only
    frame_count:
      type: integer
      maximum: 18446744073709552000
      minimum: 0
    duration_seconds:
      type: number
      minimum: 0
    quality_score:
      maximum: 1
      minimum: 0
      type:
        - number
        - "null"
    thumb_url:
      maxLength: 16384
      minLength: 1
      type:
        - string
        - "null"
    thumb_last_url:
      maxLength: 16384
      minLength: 1
      type:
        - string
        - "null"
    interface_hash:
      maxLength: 128
      type:
        - string
        - "null"
    tags:
      items:
        type: string
      type: array
      maxItems: 512
    review_state:
      type: string
      enum:
        - unreviewed
        - auto_accepted
        - human_audited
        - rejected
    metrics:
      nullable: true
      additionalProperties:
        $ref: "#/components/schemas/JsonValue"
      type: object
      maxProperties: 128
    dataset_version_id:
      format: uuid
      type:
        - string
        - "null"
    parent_episode_id:
      format: uuid
      type:
        - string
        - "null"
    parent_episode_index:
      maximum: 2147483647
      minimum: 0
      type:
        - integer
        - "null"
    member_ordinal:
      maximum: 9223372036854776000
      minimum: 0
      type:
        - integer
        - "null"
    episode_revision_id:
      pattern: ^[0-9a-f]{64}$
      type:
        - string
        - "null"
    channel_predicate_evidence:
      items:
        $ref: "#/components/schemas/LakeChannelPredicateEvidenceModel"
      type: array
      maxItems: 32
  additionalProperties: false
  type: object
  required:
    - episode_id
    - dataset_id
    - dataset_name
    - episode_index
    - frame_count
    - duration_seconds
    - review_state
    - channel_predicate_evidence
  title: LakeEpisodeModel
JsonValue: {}
LakeChannelPredicateEvidenceModel:
  properties:
    predicate_index:
      type: integer
      maximum: 31
      minimum: 0
    stream:
      type: string
      enum:
        - action
        - state
        - telemetry
    channel:
      type: string
      maxLength: 512
      minLength: 1
    agg:
      type: string
      enum:
        - max
        - min
        - mean
        - std
    op:
      type: string
      enum:
        - gt
        - lt
        - gte
        - lte
    threshold:
      type: number
    observed_value:
      type: number
    native_channel:
      type: string
      maxLength: 512
      minLength: 1
    native_index:
      type: integer
      maximum: 4294967295
      minimum: 0
  additionalProperties: false
  type: object
  required:
    - predicate_index
    - stream
    - channel
    - agg
    - op
    - threshold
    - observed_value
    - native_channel
    - native_index
  title: LakeChannelPredicateEvidenceModel
LakeFacetsModel:
  properties:
    by_task:
      items:
        $ref: "#/components/schemas/LakeFacetCountModel"
      type: array
      maxItems: 512
    by_tier:
      items:
        $ref: "#/components/schemas/LakeFacetCountModel"
      type: array
      maxItems: 512
    by_interface_hash:
      items:
        $ref: "#/components/schemas/LakeFacetCountModel"
      type: array
      maxItems: 512
    by_marker_signature:
      items:
        $ref: "#/components/schemas/LakeFacetCountModel"
      type: array
      maxItems: 512
    by_task_total_values:
      type: integer
      maximum: 18446744073709552000
      minimum: 0
    by_tier_total_values:
      type: integer
      maximum: 18446744073709552000
      minimum: 0
    by_interface_hash_total_values:
      type: integer
      maximum: 18446744073709552000
      minimum: 0
    by_marker_signature_total_values:
      type: integer
      maximum: 18446744073709552000
      minimum: 0
      default: 0
    marker_signature_unknown:
      type: integer
      maximum: 18446744073709552000
      minimum: 0
      default: 0
  additionalProperties: false
  type: object
  required:
    - by_task
    - by_tier
    - by_interface_hash
    - by_task_total_values
    - by_tier_total_values
    - by_interface_hash_total_values
  title: LakeFacetsModel
LakeFacetCountModel:
  properties:
    value:
      type: string
      maxLength: 2048
    count:
      type: integer
      maximum: 18446744073709552000
      exclusiveMinimum: 0
  additionalProperties: false
  type: object
  required:
    - value
    - count
  title: LakeFacetCountModel
ErrorResponse:
  properties:
    detail:
      type: string
      description: Error message describing what went wrong
  type: object
  required:
    - detail
  title: ErrorResponse
  description: Standard error response.
HTTPValidationError:
  properties:
    detail:
      items:
        $ref: "#/components/schemas/ValidationError"
      type: array
  type: object
  title: HTTPValidationError
ValidationError:
  properties:
    loc:
      items:
        type:
          - string
          - integer
      type: array
      title: Location
    msg:
      type: string
      title: Message
    type:
      type: string
      title: Error Type
    input: {}
    ctx:
      type: object
      title: Context
  type: object
  required:
    - loc
    - msg
    - type
  title: ValidationError
```