Datasets: programmatic access from the SDKs, CLI and MCP server

The SDKs, the CLI and the MCP server list, create, read, update and delete datasets and their records. Every call needs a LangWatch API key.

Setup

Python
TypeScript

import langwatch

# Initialize the SDK (or set LANGWATCH_API_KEY environment variable)
langwatch.setup()

import { LangWatch } from "langwatch";

const langwatch = new LangWatch();

If you are using a service API key (e.g. for CI/CD or multi-project setups), you must also set the LANGWATCH_PROJECT_ID environment variable so the SDK knows which project to access. You can find the project ID in your project settings.

List Datasets

Retrieve all datasets for your project with pagination support.

Python
TypeScript

# List all datasets (first page, default limit)
result = langwatch.dataset.list_datasets()

for ds in result.data:
    print(f"{ds.name} ({ds.slug}) - {len(ds.columnTypes)} columns")

print(f"Page {result.pagination.page} of {result.pagination.totalPages}")

# List with explicit pagination
result = langwatch.dataset.list_datasets(page=2, limit=10)

// List all datasets (first page, default limit)
const result = await langwatch.datasets.list();

for (const ds of result.data) {
  console.log(`${ds.name} (${ds.slug}) - ${ds.columnTypes.length} columns`);
}

console.log(`Page ${result.pagination.page} of ${result.pagination.totalPages}`);

// List with explicit pagination
const page2 = await langwatch.datasets.list({ page: 2, limit: 10 });

Create a Dataset

Create a new dataset with an optional column schema.

Python
TypeScript

# Create with name and column types
info = langwatch.dataset.create_dataset(
    "User Feedback",
    columns=[
        {"name": "input", "type": "string"},
        {"name": "output", "type": "string"},
    ],
)
print(f"Created: {info.name} (slug: {info.slug})")

# Create with just a name (columns can be added later)
info = langwatch.dataset.create_dataset("Simple Dataset")

// Create with name and column types
const info = await langwatch.datasets.create({
  name: "User Feedback",
  columnTypes: [
    { name: "input", type: "string" },
    { name: "output", type: "string" },
  ],
});
console.log(`Created: ${info.name} (slug: ${info.slug})`);

// Create with just a name
const simple = await langwatch.datasets.create({ name: "Simple Dataset" });

Get a Dataset

Fetch a dataset by slug or ID, including all its entries.

Python
TypeScript

# Fetch dataset by slug or ID
dataset = langwatch.dataset.get_dataset("your-dataset-slug")

# Access entries
for entry in dataset.entries:
    print(entry.id, entry.entry)

# Convert to pandas DataFrame for easy manipulation
df = dataset.to_pandas()
print(df.head())

// Fetch dataset by slug or ID
const dataset = await langwatch.datasets.get("your-dataset-slug");

// Access entries
for (const entry of dataset.entries) {
  console.log(entry.entry);
}

Update a Dataset

Update a dataset’s name or column types.

Python
TypeScript

# Update the name
updated = langwatch.dataset.update_dataset("my-dataset", name="New Name")
print(f"New slug: {updated.slug}")

# Update column types
updated = langwatch.dataset.update_dataset(
    "my-dataset",
    columns=[{"name": "question", "type": "string"}, {"name": "answer", "type": "string"}],
)

// Update the name
const updated = await langwatch.datasets.update("my-dataset", {
  name: "New Name",
});
console.log(`New slug: ${updated.slug}`);

// Update column types
const withCols = await langwatch.datasets.update("my-dataset", {
  columnTypes: [
    { name: "question", type: "string" },
    { name: "answer", type: "string" },
  ],
});

Delete a Dataset

Archive a dataset by slug or ID.

Python
TypeScript

langwatch.dataset.delete_dataset("my-dataset")

await langwatch.datasets.delete("my-dataset");

List Records

Retrieve records from a dataset with pagination.

Python
TypeScript

# List records (first page, default limit)
result = langwatch.dataset.list_records("my-dataset")

for record in result.data:
    print(record.id, record.entry)

print(f"Total: {result.pagination.total}")

# List with explicit pagination
result = langwatch.dataset.list_records("my-dataset", page=2, limit=20)

// List records (first page, default limit)
const result = await langwatch.datasets.listRecords("my-dataset");

for (const record of result.data) {
  console.log(record.id, record.entry);
}

console.log(`Total: ${result.pagination.total}`);

// List with explicit pagination
const page2 = await langwatch.datasets.listRecords("my-dataset", {
  page: 2,
  limit: 20,
});

Create Records

Batch-add records to an existing dataset.

Python
TypeScript

records = langwatch.dataset.create_records(
    "my-dataset",
    entries=[
        {"input": "What is LangWatch?", "output": "An LLM observability platform."},
        {"input": "How do I get started?", "output": "Install the SDK and call setup()."},
    ],
)
for r in records:
    print(f"Created record: {r.id}")

const records = await langwatch.datasets.createRecords("my-dataset", [
  { input: "What is LangWatch?", output: "An LLM observability platform." },
  { input: "How do I get started?", output: "Install the SDK and call setup()." },
]);
for (const r of records.data) {
  console.log(`Created record: ${r.id}`);
}

Update a Record

Update (or upsert) a single record by ID.

Python
TypeScript

record = langwatch.dataset.update_record(
    "my-dataset",
    "rec-1",
    entry={"input": "updated question", "output": "updated answer"},
)
print(f"Updated: {record.id} -> {record.entry}")

const record = await langwatch.datasets.updateRecord("my-dataset", "rec-1", {
  input: "updated question", output: "updated answer",
});
console.log(`Updated: ${record.id}`);

Delete Records

Batch-delete records by their IDs.

Python
TypeScript

deleted_count = langwatch.dataset.delete_records(
    "my-dataset",
    record_ids=["rec-1", "rec-2"],
)
print(f"Deleted {deleted_count} records")

const result = await langwatch.datasets.deleteRecords("my-dataset", ["rec-1", "rec-2"]);
console.log(`Deleted ${result.deletedCount} records`);

Upload a File

Upload a CSV, JSON, or JSONL file to a dataset. If the dataset does not exist, it is created automatically.

Python
TypeScript

# Upload to existing or create new (default: append)
result = langwatch.dataset.upload("my-dataset", file_path="data.csv")
print(f"Created {result.recordsCreated} records")

# Replace all records (delete existing, then upload)
result = langwatch.dataset.upload("my-dataset", file_path="data.csv", if_exists="replace")

# Error if dataset already exists (create-only)
result = langwatch.dataset.upload("my-dataset", file_path="data.csv", if_exists="error")

The if_exists parameter controls how conflicts are handled:

Value	Behavior
`"append"` (default)	Append rows to the existing dataset, or create it if it doesn’t exist
`"replace"`	Delete all existing records first, then upload. Creates the dataset if it doesn’t exist
`"error"`	Raise an error if the dataset already exists. Creates it otherwise

// Upload to existing or create new (default: append)
const file = new File([csvContent], "data.csv", { type: "text/csv" });
const result = await langwatch.datasets.upload("my-dataset", file);
console.log(`Created ${result.recordsCreated} records`);

// Replace all records (delete existing, then upload)
await langwatch.datasets.upload("my-dataset", file, { ifExists: "replace" });

// Error if dataset already exists (create-only)
await langwatch.datasets.upload("my-dataset", file, { ifExists: "error" });

The ifExists parameter controls how conflicts are handled:

Value	Behavior
`"append"` (default)	Append rows to the existing dataset, or create it if it doesn’t exist
`"replace"`	Delete all existing records first, then upload. Creates the dataset if it doesn’t exist
`"error"`	Throw an error if the dataset already exists. Creates it otherwise

Using with Evaluations

Datasets are commonly used to run offline evaluations against your LLM or agent.

Python
TypeScript

import langwatch

langwatch.setup()

# Fetch dataset
df = langwatch.dataset.get_dataset("your-dataset-slug").to_pandas()

# Initialize evaluation
evaluation = langwatch.experiment.init("my-evaluation")

for index, row in evaluation.loop(df.iterrows()):
    # Run your LLM/agent
    output = my_llm(row["input"])

    # Log evaluation metrics
    evaluation.log("response_quality", index=index, score=0.9)

import { LangWatch } from "langwatch";

const langwatch = new LangWatch();

// Fetch dataset
const dataset = await langwatch.datasets.get("your-dataset-slug");

// Initialize evaluation
const evaluation = await langwatch.experiments.init("my-evaluation");

await evaluation.run(
  dataset.entries.map((e) => e.entry),
  async ({ item, index }) => {
    // Run your LLM/agent
    const output = await myLLM(item.input);

    // Log evaluation metrics
    evaluation.log("response_quality", { index, score: 0.9 });
  },
  { concurrency: 4 }
);

Dataset Entry Structure

Each dataset entry contains:

Field	Description
`id`	Unique identifier for the entry
`entry`	The actual data (e.g., `input`, `expected_output`, `contexts`)
`datasetId`	ID of the parent dataset
`projectId`	ID of the project
`createdAt`	Timestamp of creation
`updatedAt`	Timestamp of last update

Which fields you get back depends on the operation. list_records returns all six. create_records returns id, entry and createdAt. In Python, get_dataset returns entries with id and entry only.

Typed Datasets (TypeScript)

You can define types for your dataset entries for better type safety:

type MyDatasetEntry = {
  input: string;
  expected_output: string;
  contexts?: string[];
};

const dataset = await langwatch.datasets.get<MyDatasetEntry>("my-dataset");

// Now entry.entry is typed as MyDatasetEntry
for (const entry of dataset.entries) {
  console.log(entry.entry.input);  // Typed as string
  console.log(entry.entry.expected_output);  // Typed as string
}

CLI

The langwatch CLI has the same operations. Set LANGWATCH_API_KEY and run:

langwatch dataset list
langwatch dataset create "User Feedback" --columns input:string,output:string
langwatch dataset get user-feedback
langwatch dataset update user-feedback --name "Support feedback"
langwatch dataset upload user-feedback ./rows.csv --if-exists append
langwatch dataset download user-feedback --format jsonl
langwatch dataset delete user-feedback

langwatch dataset records list user-feedback --page 1 --limit 20
langwatch dataset records add user-feedback --file ./records.json
langwatch dataset records update user-feedback RECORD_ID --json '{"input": "..."}'
langwatch dataset records delete user-feedback RECORD_ID

A service API key also needs LANGWATCH_PROJECT_ID, so the CLI knows which project to use. A project API key from the project settings page already carries the project. --if-exists takes append (default), replace or error. records add reads a JSON array from --json, --file or --stdin. Every command accepts --format json for machine-readable output.

MCP Tools (AI Coding Agents)

If you’re using an AI coding agent (Claude Code, Cursor, etc.) with the LangWatch MCP server, dataset tools are available directly:

Tool	Description
`platform_list_datasets`	List all datasets with record counts
`platform_get_dataset`	Get dataset metadata, columns, and record preview
`platform_create_dataset`	Create a new dataset with optional column definitions
`platform_update_dataset`	Update dataset name or column types
`platform_delete_dataset`	Archive a dataset
`platform_list_dataset_records`	List the records of a dataset, one page at a time
`platform_create_dataset_records`	Add records in batch (max 1000)
`platform_update_dataset_record`	Update a single record
`platform_delete_dataset_records`	Delete records by IDs

The platform_list_datasets, platform_get_dataset and platform_list_dataset_records tools support a format parameter, use "json" for raw data or "digest" (default) for AI-readable markdown.

Finding Your Dataset Slug or ID

Every call accepts the dataset slug or its ID.

Go to the Datasets page and click your dataset.
The URL reads app.langwatch.ai/{project}/datasets/{id}; the ID starts with dataset_.
The slug is shown under the Name field when you open Edit columns, and in the slug field of every SDK and CLI response.

Get Started

Agent Testing

Observability

Evaluations

Prompt Management

Platform

Examples & Cookbooks

Help

Datasets: programmatic access from the SDKs, CLI and MCP server

Setup

List Datasets

Create a Dataset

Get a Dataset

Update a Dataset

Delete a Dataset

List Records

Create Records

Update a Record

Delete Records

Upload a File

Using with Evaluations

Dataset Entry Structure

Typed Datasets (TypeScript)

CLI

MCP Tools (AI Coding Agents)

Finding Your Dataset Slug or ID

​Setup

​List Datasets

​Create a Dataset

​Get a Dataset

​Update a Dataset

​Delete a Dataset

​List Records

​Create Records

​Update a Record

​Delete Records

​Upload a File

​Using with Evaluations

​Dataset Entry Structure

​Typed Datasets (TypeScript)

​CLI

​MCP Tools (AI Coding Agents)

​Finding Your Dataset Slug or ID

Setup

List Datasets

Create a Dataset

Get a Dataset

Update a Dataset

Delete a Dataset

List Records

Create Records

Update a Record

Delete Records

Upload a File

Using with Evaluations

Dataset Entry Structure

Typed Datasets (TypeScript)

CLI

MCP Tools (AI Coding Agents)

Finding Your Dataset Slug or ID