# Datasets API

> Create and manage reusable, governed datasets under /api/datasets.

*[View this page in the Flax docs](https://flax-analytics.com/docs/api-reference/datasets)*

Datasets are reusable, governed sources promoted from a saved query or a sheet
selection. A `live` dataset stores a query that recompiles each run; a `snapshot`
freezes point-in-time values. Charts reference a dataset by its `slug` as their model.
Listing needs the `read` scope; creating needs `write`; deleting needs `manage`.

## List datasets

- `GET /api/datasets` — every dataset the account can read.
- `GET /api/projects/{projectId}/datasets` — the datasets in one semantic layer.

## Get a dataset

`GET /api/datasets/{datasetId}` — one dataset (its kind, slug, and definition).

## Create a dataset

`POST /api/projects/{projectId}/datasets` — promote a query into a dataset. `kind` is
`live` (pass `definition`, an exploration) or `snapshot` (pass `snapshotCsv`).

```bash
curl -X POST https://flax-analytics.com/api/projects/{projectId}/datasets \
  -H "Authorization: Bearer flax_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Active bookings","kind":"live","definition":{"model":"fct_bookings"}}'
```

Datasets are immutable — to change one, delete and recreate.

## Usage and delete

- `GET /api/datasets/{datasetId}/usage` — the charts and dashboards that reference the
  dataset (its lineage). Check before deleting.
- `DELETE /api/datasets/{datasetId}` — remove it (`manage`). Blocked with `409` while a
  chart still references it.

## Related

- [Modeling overview](/docs/modeling/overview)