> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Datasets

> Create a dataset by hand, from a CSV or JSON file, or from your traces, edit it in the grid, and run an experiment on it.

> [!TIP]
>
> **Let your agent set this up.** [Copy the evaluations prompt](https://langwatch.ai/docs/skills/directory.md) into your coding agent to get started automatically.

A dataset is a table of rows your experiments run on. Each column has a name and a type, and each row is one case: an input, the expected output when you have one, and any other field your prompt or evaluator reads.

![A dataset page with rows in the grid and the Download as CSV, Add rows, Edit columns and Run experiment buttons](https://mintcdn.com/langwatch/iG2HKiUWiJlQldW1/images/datasets/dataset-editor.png?fit=max\&auto=format\&n=iG2HKiUWiJlQldW1\&q=85\&s=a3537692cd6b8a1069dc06a825b13d55)

## Create a dataset

Open [Datasets](https://app.langwatch.ai/@project/datasets) and click **Upload or create dataset**.

![The Datasets list with the Upload or create dataset menu open](https://mintcdn.com/langwatch/iG2HKiUWiJlQldW1/images/datasets/datasets-list.png?fit=max\&auto=format\&n=iG2HKiUWiJlQldW1\&q=85\&s=2f9718464ad8c69a1297bd06e62a0cc2)

The menu has two entries:

| Entry | What it does |
| - | - |
| **Upload datasets** | Creates one dataset per file from CSV, JSON or JSONL files. |
| **Create empty dataset** | Opens the **New Dataset** drawer where you name the dataset and define its columns. |

### Create an empty dataset

In the **New Dataset** drawer, type a **Name**; the slug under it is what the SDKs and the CLI use. Then define the **Columns**. A new dataset starts with `trace_id`, `timestamp`, `input`, `output`, `contexts`, `total_cost` and `annotations`. Remove the columns you do not need, click **Add Column** for the ones you do, and click **Create Dataset**. The type select on each column offers `string`, `number`, `boolean`, `date`, `list`, `json`, `image`, `file`, `json chat messages (OpenAI format)` and `json spans`.

![The New Dataset drawer with the name, its slug, and the default columns with their types](https://mintcdn.com/langwatch/iG2HKiUWiJlQldW1/images/datasets/dataset-new-drawer.png?fit=max\&auto=format\&n=iG2HKiUWiJlQldW1\&q=85\&s=2f960264804185fcdfd0dfcc379a66f8)

Column names must be unique and cannot be `id` or `selected`. Each column has one of these types:

| Type | Holds |
| - | - |
| `string` | Text. Use it for `input`, `output` and `expected_output`. |
| `number` | A number, for example a cost or a token count. |
| `boolean` | `true` or `false`. |
| `date` | A timestamp. |
| `list` | A list of strings, for example retrieved contexts. |
| `json` | Any JSON value. |
| `image` | A picture. The cell takes an uploaded file, a URL or a data URL, and the grid renders it as a thumbnail. See [Images and files in datasets](https://langwatch.ai/docs/datasets/dataset-images.md). |
| `file` | Any other document, for example a PDF, an audio clip or a CSV. The cell takes an uploaded file, a URL or a data URL. See [Images and files in datasets](https://langwatch.ai/docs/datasets/dataset-images.md). |
| `json chat messages (OpenAI format)` | A list of chat messages with `role` and `content`. |
| `json spans` | The spans of a trace, as JSON. |

### Upload files

**Upload datasets** opens a drawer that accepts CSV, JSON and JSONL files, several at a time. Each file becomes one dataset. For each file, edit the dataset name, then check the columns read from the file. A CSV gives its columns from the header row, a JSON or JSONL file from the object keys. Rename a column, change its type, drag it to reorder, or exclude it. Click **Upload all**.

![The Upload datasets drawer with a CSV file added and its columns listed](https://mintcdn.com/langwatch/iG2HKiUWiJlQldW1/images/datasets/dataset-upload-drawer.png?fit=max\&auto=format\&n=iG2HKiUWiJlQldW1\&q=85\&s=a2ba9c51abf11fd90f69d4efe0545a70)

A file can be up to 5 GB. A large file shows **Processing** in the list until its rows are stored.

## Edit a dataset

Click a dataset in the list to open its page. The header shows the record count and an autosave status.

| Button | What it does |
| - | - |
| **Download as CSV** | Exports every row. |
| **Add rows** | Opens **Add rows from CSV**. Each dataset column has a **Select column** control that lists the columns of your file and **Set empty**. Map every column, then click **Upload**, which stays disabled until the file is attached. |
| **Edit columns** | Opens the dataset drawer to add, rename, retype or remove columns. |
| **Run experiment** | Opens the Experiments Workbench with this dataset loaded. See [Experiments](https://langwatch.ai/docs/evaluations/experiments/overview.md). |

![The Add rows from CSV modal with a CSV file attached and a Select column control for the input and expected\_output columns](https://mintcdn.com/langwatch/b_7qlc4BhHkq6ZDw/images/datasets/dataset-add-rows-csv.png?fit=max\&auto=format\&n=b_7qlc4BhHkq6ZDw\&q=85\&s=f456ec6558fb89361c5cb6e2cf763f13)

Click a cell to edit it. **Add row** under the grid appends an empty row. Select rows with the checkboxes and click **Delete** to remove them. Every change saves as you make it.

The row menu in the datasets list has **Replicate to another project**, **Edit dataset** and **Delete dataset**. A deleted dataset can be restored from the toast for 10 seconds.

## Add rows from traces

Open the [Trace Explorer](https://app.langwatch.ai/@project/traces), select the traces with the checkboxes, and click **Add to dataset** in the action bar. From an open trace, the header menu has **Add trace to dataset** and, for a multi-turn conversation, **Add conversation to dataset**.

![The Trace Explorer with three traces selected and the action bar: Export selected, Add to context, Add to annotation queue and Add to dataset](https://mintcdn.com/langwatch/iG2HKiUWiJlQldW1/images/datasets/trace-explorer-add-to-dataset.png?fit=max\&auto=format\&n=iG2HKiUWiJlQldW1\&q=85\&s=2053971d802acf8217f2feb072a4c672)

The **Add to Dataset** drawer has three parts:

1. **Dataset**: pick an existing dataset, or click **+ Create New**.
2. **Mapping**: one source per dataset column. **Current Trace** maps each trace to one row. **Thread** groups the selected traces by `thread_id` and maps each conversation to one row. See [Threads in datasets](https://langwatch.ai/docs/datasets/dataset-threads.md).
3. **Preview**: the rows that will be added. Double-click a cell to edit it, and untick a row to leave it out.

![The Add to Dataset drawer with the Current Trace mapping of input and output onto the dataset columns and the three preview rows that will be added](https://mintcdn.com/langwatch/b_7qlc4BhHkq6ZDw/images/datasets/add-to-dataset-drawer.png?fit=max\&auto=format\&n=b_7qlc4BhHkq6ZDw\&q=85\&s=a6b6e8822f43390ea5888e811b944bf6)

Click **Add N rows to dataset**. LangWatch remembers the mapping per dataset, so the next time you add traces to it the mapping is already set.

The sources a column can map to are the trace fields: `trace_id`, `thread_id`, `timestamp`, `input`, `output`, `contexts`, the `metrics` (cost, tokens, timings), `spans`, `metadata` keys, `evaluations` per evaluator, `annotations` (comment, score, reason, expected output), `events`, and **Full Trace (AI-Readable)**, a text rendering of the whole trace for an LLM to read. When a column name matches a source, for example `input` or `output`, the mapping is filled in for you.

To keep adding matching traces as they arrive, use an automation. See [Build datasets from traces automatically](https://langwatch.ai/docs/datasets/automatically-from-traces.md).

## Manage datasets from code

The Python and TypeScript SDKs, the CLI, the MCP server and the REST API list, create, read and update datasets and their rows. See [Programmatic access](https://langwatch.ai/docs/datasets/programmatic-access.md).

**Also check:** [Experiments](https://langwatch.ai/docs/evaluations/experiments/overview.md) to run a dataset through your prompts and score every row, and [Annotations](https://langwatch.ai/docs/annotations/queues.md) to send reviewed traces to a dataset at the end of a review session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.