# List User Datasets

`GET /v1/datasets/list`

List published QDS datasets for exactly one authorized account.

The legacy artifact/job catalog is deliberately not consulted. QDS's
canonical dataset UUID is the stable public identity; source format is a
persisted ingest fact, never inferred from filenames or another service.

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

## Parameters

- `dataset_type` (query, string): Filter by the persisted QDS source format One of: `lerobot_v2_1`, `lerobot_v3`, `mcap_ros2`.

  ```yaml
  nullable: true
  type: string
  ```
- `account_id` (query, string | null (uuid)): Scope to this account (the dashboard's active account). Membership is verified upstream; a non-member gets 403.
- `search` (query, string | null): Search dataset path

  ```yaml
  maxLength: 200
  type:
    - string
    - "null"
  ```
- `limit` (query, integer)

  ```yaml
  type: integer
  maximum: 100
  minimum: 1
  default: 20
  ```
- `cursor` (query, string | null): Pagination cursor

  ```yaml
  maxLength: 2048
  type:
    - string
    - "null"
  ```
- `sort` (query, string)

  ```yaml
  const: name
  type: string
  default: name
  ```

## Responses

- `200` Paginated list of user's datasets: `application/json` `PaginatedDatasetsResponse`
- `401` Invalid or missing API key: `application/json` `ErrorResponse`
- `422` Invalid pagination parameters

## Schemas

```yaml
PaginatedDatasetsResponse:
  properties:
    items:
      items:
        $ref: "#/components/schemas/DatasetItem"
      type: array
    page_info:
      $ref: "#/components/schemas/PageInfo"
  type: object
  required:
    - page_info
  title: PaginatedDatasetsResponse
DatasetItem:
  properties:
    artifact_id:
      type: string
      format: uuid
      description: Artifact ID
    subtype:
      type: string
      description: Dataset subtype (lerobot_v2_1, lerobot_v3, mcap_ros2)
    artifact_subtype:
      description: Alias of subtype
      type:
        - string
        - "null"
    path:
      type: string
      description: Dataset path (org/name)
    metadata:
      additionalProperties: true
      type: object
    jobs:
      items:
        $ref: "#/components/schemas/JobLink"
      type: array
    published_at:
      type: string
      format: date-time
      description: Immutable timestamp of the first successful structured QDS publication
    qds:
      description: QDS catalog facts (P6a)
      nullable: true
      allOf:
        - $ref: "#/components/schemas/DatasetQdsFacts"
  type: object
  required:
    - artifact_id
    - subtype
    - path
    - published_at
  title: DatasetItem
JobLink:
  properties:
    job_id:
      type: string
      format: uuid
    direction:
      type: string
      description: input or output
  type: object
  required:
    - job_id
    - direction
  title: JobLink
DatasetQdsFacts:
  properties:
    repo_id:
      format: uuid
      type:
        - string
        - "null"
    size_bytes:
      description: REAL logical bytes (file sizes sum)
      minimum: 0
      type:
        - integer
        - "null"
    file_count:
      minimum: 0
      type:
        - integer
        - "null"
    dataset_id:
      format: uuid
      type:
        - string
        - "null"
    episode_count:
      minimum: 0
      type:
        - integer
        - "null"
    total_frames:
      minimum: 0
      type:
        - integer
        - "null"
    quality_avg:
      description: Mean of STORED episode quality scores
      type:
        - number
        - "null"
    scored_episodes:
      description: How many episodes have a stored score
      minimum: 0
      type:
        - integer
        - "null"
    ingest_verdict:
      description: "Upload verdict: published | degraded | underivable (no episode could be derived; the raw bytes are kept). Null = not recorded, read as published."
      type:
        - string
        - "null"
    verdict_reason:
      description: 'Why, as "<finding code>: <message>"; null when published'
      type:
        - string
        - "null"
  type: object
  title: DatasetQdsFacts
  description: |-
    QDS-sourced catalog facts (P6a). Only present when the deployment's
    data plane is QDS and the repo resolved; fields beyond size/file_count
    need a structured dataset row. Absent means absent — never rendered
    as zero.
PageInfo:
  properties:
    has_next:
      type: boolean
      description: Whether more items exist after this page
    end_cursor:
      description: Cursor for the next page
      type:
        - string
        - "null"
    total_count:
      description: Total matching items
      type:
        - integer
        - "null"
  type: object
  required:
    - has_next
  title: PageInfo
ErrorResponse:
  properties:
    detail:
      type: string
      description: Error message describing what went wrong
  type: object
  required:
    - detail
  title: ErrorResponse
  description: Standard error response.
```