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

# List Datasets

`GET /v1/datasets`

This endpoint returns a list of configured datasets. The response can be formatted as **JSON** or **CSV**,
and additional filters can be applied using query parameters.

Use `status=true` query parameter to include the current status of each dataset in the response.
Possible status values: `initializing`, `ready`, `disabled`, `error`, `refreshing`, `shuttingdown`.
When `status=true` and a dataset is in `Error`, the response also includes:
- `error`: structured code object with `category`, `type`, and stable `code`
- `error_message`: user-visible details

## Query parameters

- `status` boolean
- `format` 'json' | 'csv'
- `source` string, nullable

## Response `200`

List of datasets. When `status=true` is specified, each dataset includes `status` and error metadata (`error`, `error_message`) when applicable.

- DatasetInfo — Dataset information returned by the `/v1/datasets` endpoint.
  - `acceleration_enabled` boolean, required — Whether acceleration is enabled for the dataset
  - `error` ComponentError
    - `category` 'dataset' | 'model' | 'worker' | 'runtime', required
    - `code` string, required — Stable machine-readable code (`{category}.{type}`), e.g. `dataset.auth`.
    - `type` 'auth' | 'connection' | 'timeout' | 'validation' | 'not_found' | 'permission' | 'rate_limit' | 'internal' | 'unknown', required
  - `error_message` string, nullable — An optional error message describing why the dataset entered an error state. Only populated when `status=true`, the dataset status is `Error`, and an error message was recorded. This value is intended for user-visible display.
  - `from` string, required — The source where the dataset is located (e.g., `postgres:syncs`)
  - `name` string, required — The name of the dataset
  - `properties` object — Custom properties for the dataset
  - `replication_enabled` boolean, required — Whether replication is enabled for the dataset
  - `status` union — Represents the status of a component (e.g. dataset, model, etc). The `Error` variant optionally carries a human-readable error message describing what caused the component to enter the error state. Use [`ComponentStatus::error`] for an error without a message, or [`ComponentStatus::error_with_message`] to include one.
    - 'Initializing' — The component is initializing and not yet ready
    - 'Ready' — The component is ready to accept connections
    - 'Disabled' — The component is disabled and not running
    - object — An error occurred in the component, with an optional error message
      - `Error` string, nullable, required — An error occurred in the component, with an optional error message
    - 'Refreshing' — The component is in the process of refreshing its state
    - 'ShuttingDown' — The component is in the process of shutting down
    - 'NotLoaded' — The component is configured but not loaded yet

## Other responses

- `500` — Internal server error occurred while processing datasets

## Changes

- **2026-05-05** `d375369a0861` — 1 breaking
  - added `subschema #7` to the `status/oneOf[#/components/schemas/String]/` response property `oneOf` list for the response status `200`
- **2026-03-17** `934753ac3413` — 1 breaking, 3 info
  - added `#/components/schemas/String` to the `status` response property `oneOf` list for the response status `200` (media type: application/json)
  - added the optional property `error` to the response with the `200` status (media type: application/json)
  - added the optional property `error_message` to the response with the `200` status (media type: application/json)
  - removed `#/components/schemas/ComponentStatus` from the `status` response property `oneOf` list for the response status `200` (media type: application/json)
- **2025-03-18** `dd94571fef79` — 1 breaking, 2 warning, 1 info
  - added `#/components/schemas/ComponentStatus` to the `status` response property `oneOf` list for the response status `200` (media type: application/json)
  - removed the optional property `error` from the response with the `200` status (media type: application/json)
  - removed the optional property `error_message` from the response with the `200` status (media type: application/json)
  - removed `#/components/schemas/String` from the `status` response property `oneOf` list for the response status `200` (media type: application/json)

[Change history](https://skmtc.dev/spiceai/apis/runtime/changes/v1/datasets/get.md)

---

[API](https://skmtc.dev/spiceai/apis/runtime.md) · [All operations](https://skmtc.dev/spiceai/apis/runtime/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spiceai/runtime/revisions/f4bb5537fc13/schema)