Skip to content
Qualia Docs

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

POST
/v1/datasets/explore
 
curl --request POST \
  --url https://example.com/v1/datasets/explore \
  --header 'Content-Type: application/json' \
  --data '{ "tasks": [ "example" ], "tiers": [ "" ], "interface_hashes": [ "example" ], "tags": [ "example" ], "review_state": "", "dataset_ids": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "episode_index": 1, "limit": 50, "offset": 0, "search": "", "numeric_predicates": [ { "field": "duration_s", "op": "gt", "value": 1 } ], "channel_predicates": [ { "stream": "action", "channel": "example", "agg": "max", "op": "gt", "value": 1 } ] }'

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.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
account_id

Act on this account (active)

string | null format: uuid

Act on this account (active)

Header Parameters

Section titled “Header Parameters ”
x-api-key
string | null

Request Body required

Section titled “Request Body required ”
Media type application/json
ExploreLakeBody
object
tasks
Array<string>
<= 512 items
tiers
Array<string>
<= 512 items
Allowed values: "" retrainable analyze_only
interface_hashes
Array<string>
<= 512 items
tags
Array<string>
<= 512 items
review_state
string
""
Allowed values: "" unreviewed auto_accepted human_audited rejected
dataset_ids
Array<string>
<= 4096 items
episode_index
integer | null
<= 2147483647
limit
integer
default: 50 >= 1 <= 200
offset
integer
0 <= 4294967295
search
string
""
numeric_predicates
Array<object>
<= 32 items
NumericPredicateBody
object
field
required
string
Allowed values: 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
required
string
Allowed values: gt lt gte lte
value
required
number
channel_predicates
Array<object>
<= 32 items
ChannelPredicateBody
object
stream
string
default: action
Allowed values: action state telemetry
channel
required
string
agg
required
string
Allowed values: max min mean std
op
required
string
Allowed values: gt lt gte lte
value
required
number

Responses

Section titled “ Responses ”

200

Section titled “200 ”

One internally consistent live-MVCC page, filtered totals, bounded self-excluding facets with full cardinalities, and independently checkable channel-predicate evidence

Media type application/json
ExploreLakeResponseModel
object
episodes
required
Array<object>
<= 200 items
LakeEpisodeModel
object
episode_id
required
string format: uuid
dataset_id
required
string format: uuid
dataset_name
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
episode_index
required
integer
<= 4294967295
task
string | null
<= 262144 characters
tier
string
nullable
Allowed values: retrainable analyze_only
frame_count
required
integer
<= 18446744073709552000
duration_seconds
required
number
quality_score
number | null
<= 1
thumb_url
null
interface_hash
string | null
<= 128 characters
tags
Array<string>
<= 512 items
review_state
required
string
Allowed values: unreviewed auto_accepted human_audited rejected
metrics
object
<= 128 properties
key
additional properties
dataset_version_id
string | null format: uuid
member_ordinal
integer | null
<= 9223372036854776000
episode_revision_id
string | null
/^[0-9a-f]{64}$/
channel_predicate_evidence
required
Array<object>
<= 32 items
LakeChannelPredicateEvidenceModel
object
predicate_index
required
integer
<= 31
stream
required
string
Allowed values: action state telemetry
channel
required
string
>= 1 characters <= 512 characters
agg
required
string
Allowed values: max min mean std
op
required
string
Allowed values: gt lt gte lte
threshold
required
number
observed_value
required
number
native_channel
required
string
>= 1 characters <= 512 characters
native_index
required
integer
<= 4294967295
total
required
integer
<= 18446744073709552000
total_frames
required
integer
<= 18446744073709552000
total_duration_seconds
required
number
facets
required
LakeFacetsModel
object
by_task
required
Array<object>
<= 512 items
LakeFacetCountModel
object
value
required
string
<= 512 characters
count
required
integer
> 0 <= 18446744073709552000
by_tier
required
Array<object>
<= 512 items
LakeFacetCountModel
object
value
required
string
<= 512 characters
count
required
integer
> 0 <= 18446744073709552000
by_interface_hash
required
Array<object>
<= 512 items
LakeFacetCountModel
object
value
required
string
<= 512 characters
count
required
integer
> 0 <= 18446744073709552000
by_task_total_values
required
integer
<= 18446744073709552000
by_tier_total_values
required
integer
<= 18446744073709552000
by_interface_hash_total_values
required
integer
<= 18446744073709552000
page_limit
required
integer
>= 1 <= 200
page_offset
required
integer
<= 4294967295
Example 
{
  "episodes": [
    {
      "tier": "retrainable",
      "review_state": "unreviewed",
      "channel_predicate_evidence": [
        {
          "stream": "action",
          "agg": "max",
          "op": "gt"
        }
      ]
    }
  ]
}

400

Section titled “400 ”

QDS data plane not enabled

401

Section titled “401 ”

Invalid or missing API key

Media type application/json
ErrorResponse

Standard error response.

object
detail
required

Error message describing what went wrong

string
Example generated
{
  "detail": "example"
}

422

Section titled “422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Array<object>
ValidationError
object
loc
required
Location
Array<string | integer>
msg
required
Message
string
type
required
Error Type
string
input
ctx
Context
object
Example generated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}