---
title: "List Datasets"
method: GET
path: "/felix/datasets"
tags: ["felix", "datasets"]
---

# List Datasets

`GET /felix/datasets`

Lists visible datasets.

## Query parameters

- `include_all_versions` boolean
- `project_id` string, nullable — Filter by project ID. For a real project, orphan (no-project) datasets are included only when include_orphans=True. Omitted or the 'default' sentinel always includes orphans.
- `include_failed` boolean — When true, include the caller's own failed datasets (status='failed'). Defaults to false so the UI never renders broken-but-clickable records that 404 on preview/analyze. The result set is always scoped to the authenticated user — this flag does NOT grant cross-user visibility, so passing true is safe for any authenticated caller. Failed rows remain in the database for support / debugging; their original upload is preserved at raw_s3_key.
- `include_orphans` boolean — When true and project_id names a real project, also include the caller's own orphan (no-project) datasets alongside the project's own rows. Ignored when project_id is omitted or is the 'default' sentinel, where orphans are always included regardless. Defaults to false so an ordinary project-scoped list stays scoped to the project instead of being swamped by every one of the caller's orphans; set this explicitly from surfaces that deliberately want orphans folded in, e.g. the MLE agent's dataset picker (ENG-6077).
- `limit` integer, nullable — Maximum datasets to return, newest first, after collapsing to the latest version per name. Defaults to and is bounded at 200 (oversize requests are rejected, matching /felix/training-jobs and /projects/{id}/evaluation-runs). Callers that need the full set page with limit/offset (ENG-7085): the frontend datasets tab and the sandbox dataset picker both loop until a short page rather than issuing one unbounded read.
- `offset` integer — Number of leading datasets to skip.

## Response `200`

Successful Response

- DatasetListResponse — Response model for listing datasets.
  - `success` boolean
  - `datasets` DatasetResponse[], required
    - `id` string, required
    - `user_id` string, required
    - `dataset_name` string, required
    - `dataset_path` string, required
    - `dataset_type` string, required
    - `size` integer, nullable
    - `sample_size` integer, nullable
    - `train_ratio` number, nullable — Train split ratio for this dataset version. Left-to-right split with no shuffle; validation is the tail.
    - `created_at` string, required
    - `updated_at` string, required
    - `version_number` string
    - `root_dataset_id` string, nullable
    - `project_id` string, nullable
    - `schema` object, nullable
    - `schema_warnings` string[], nullable
    - `validation` object, nullable
    - `annotation_status` 'none' | 'in_progress' | 'completed', nullable
    - `annotation_config` object, nullable
    - `annotation_progress` object, nullable
    - `status` 'initialized' | 'uploading' | 'converting' | 'validating' | 'ready' | 'failed' | 'generating' | 'queued', nullable — Dataset status: initialized/uploading/converting/validating/ready/failed/generating/queued
    - `processing_error` string, nullable — Error message if status is failed
    - `type` string — Dataset purpose tag: 'training', 'evaluation', or 'benchmark'
    - `visibility` string — Dataset visibility: 'private' or 'public'
    - `is_competition` boolean — Whether this dataset is a competition benchmark
    - `labels` string[], nullable — Label names (entity types for NER, class labels for classification)
    - `generation_type` string, nullable — Canonical operation that created this dataset version.
    - `provenance` DatasetProvenance — Record how a dataset was created and which inputs produced it. Attributes: schema_version: Contract version for future migrations. method: Canonical dataset generation type. sources: External source descriptors. fallback: Fallback reason and attempt count, when one was required. source_dataset_ids: Dataset inputs combined or transformed. parent_dataset_id: Immediate dataset version or transform parent. transform_context: Bounded details about a transform. generator_context: Bounded generator configuration or agent context. synthesis_session_id: Synthesis-log session shared with the dataset row.
      - `schema_version` 1
      - `method` 'synthesize' | 'upload' | 'external' | 'grow' | 'augment' | 'version' | 'merge' | 'auto_relabel' | 'manual_relabel' | 'evaluation_suite' | 'agent_curated', required
      - `sources` DatasetProvenanceSource[]
        - `url` string, nullable
        - `revision` string, nullable
        - `license` string, nullable
        - `retrieved_at` string, date-time, nullable
        - `raw_hash` string, nullable
      - `fallback` DatasetProvenanceFallback — Describe a fallback used after the preferred source or strategy failed. Attributes: reason: Why the preferred path could not be used. attempts: Number of attempts made before the fallback succeeded.
        - `reason` string, required
        - `attempts` integer, required
      - `source_dataset_ids` string[]
      - `parent_dataset_id` string, nullable
      - `transform_context` JsonObjectOutput
      - `generator_context` JsonObjectOutput
      - `synthesis_session_id` string, nullable
    - `is_seed` boolean, nullable — Whether this dataset is a seed dataset (small set for review before full expansion)
    - `synthesis_session_id` string, nullable — UUID of the synthesis log session for this dataset, used to restore creation workflow on resume
    - `column_mapping` object, nullable — Column mapping from original to standard names
  - `count` integer, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-24** `1cffaad2a921` — 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the new optional `query` request parameter `include_orphans`
  - added the new optional `query` request parameter `limit`
  - added the new optional `query` request parameter `offset`
  - …2 more

[Change history](https://skmtc.dev/pioneer/apis/brain-api/changes/felix/datasets/get.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) · [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/1cffaad2a921?raw)