Export annotated data

Export your annotated data to use in external evaluation frameworks, custom analysis pipelines, reporting, or training workflows. Braintrust provides multiple export methods to fit your needs.

Download data directly from the Braintrust dashboard:

Export logs

Navigate to the Logs page.
Apply filters to select the data you want.
Select the export icon.
Choose format (JSON or CSV).
Download the file.

Export datasets

Navigate to your dataset.
Apply filters if needed.
Select the export icon.
Choose format.
Download the file.

Export experiments

Open an experiment.
Select the export icon.
Choose format.
Download results including inputs, outputs, scores, and metadata.

Read datasets or logs programmatically and export to your preferred format:

import { initDataset } from "braintrust";
import fs from "fs";

async function exportDataset() {
  const dataset = initDataset("My App", { dataset: "My Dataset" });
  const records = [];

  for await (const row of dataset) {
    records.push({
      input: row.input,
      expected: row.expected,
      metadata: row.metadata,
    });
  }

  // Export as JSON
  fs.writeFileSync(
    "dataset-export.json",
    JSON.stringify(records, null, 2)
  );

  // Or convert to CSV, Parquet, etc.
}

exportDataset();

Filter before export

Use BTQL filtering to export specific subsets:

const dataset = initDataset("My App", {
  dataset: "My Dataset",
  _internal_btql: {
    filter: { btql: "metadata.annotated = true" },
    sort: [{ expr: { btql: "created" }, dir: "desc" }],
    limit: 1000,
  },
});

const records = [];
for await (const row of dataset) {
  records.push(row);
}

Query and export data programmatically using the SQL query API endpoint:

curl -X POST https://api.braintrust.dev/btql \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM project_logs('"'<PROJECT_ID>'"') WHERE tags INCLUDES '"'annotated'"'",
    "fmt": "json"
  }'

Export formats

The API supports two formats via the fmt parameter:

json (default): Returns data as JSON for easy processing
parquet: Returns data in Parquet format for data warehouses and analytics tools

Export parameters

query (required): Your SQL query selecting the data to export
fmt: Response format (json or parquet)
tz_offset: Timezone offset in minutes for correct timestamps
audit_log: Include audit trail data showing who made changes

Export examples

Export logs with user feedback:

curl -X POST https://api.braintrust.dev/btql \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM project_logs('"'<PROJECT_ID>'"') WHERE scores.user_rating > 0.8 LIMIT 1000",
    "fmt": "parquet"
  }'

Export dataset records:

curl -X POST https://api.braintrust.dev/btql \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT input, expected, metadata FROM project_dataset('"'<PROJECT_ID>'"', '"'<DATASET_ID>'"')",
    "fmt": "json"
  }'

Common export workflows

Build training datasets

Export annotated examples for fine-tuning:

curl -X POST https://api.braintrust.dev/btql \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT input, expected FROM project_dataset('"'<PROJECT_ID>'"', '"'<DATASET_ID>'"') WHERE expected IS NOT NULL",
    "fmt": "json"
  }'

Extract user corrections

Export traces where users provided corrections:

curl -X POST https://api.braintrust.dev/btql \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT input, output, expected, metadata.user_id FROM project_logs('"'<PROJECT_ID>'"') WHERE expected IS NOT NULL AND metadata.user_correction = true",
    "fmt": "json"
  }'

Generate reports

Export performance data for reporting:

curl -X POST https://api.braintrust.dev/btql \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT created, scores.user_rating, scores.accuracy, metadata.model FROM project_logs('"'<PROJECT_ID>'"') WHERE created > now() - interval 7 day",
    "fmt": "parquet"
  }'

Preserve annotations

When exporting, all annotations are preserved:

Tags: Included in the exported data
Comments: Available in the metadata
Expected values: Exported with each record
Scores: All score values included
Metadata: Custom fields maintained

This ensures your annotations remain useful in external tools.

Next steps

Run evaluations with exported datasets
Build prompts using annotated examples
Create scorers based on labeled data
Read the SQL reference for advanced queries

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Export annotated data

Export logs

Export datasets

Export experiments

Filter before export

Export formats

Export parameters

Export examples

Common export workflows

Build training datasets

Extract user corrections

Generate reports

Preserve annotations

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

​Export logs

​Export datasets

​Export experiments

​Filter before export

​Export formats

​Export parameters

​Export examples

​Common export workflows

​Build training datasets

​Extract user corrections

​Generate reports

​Preserve annotations

​Next steps

Export logs

Export datasets

Export experiments

Filter before export

Export formats

Export parameters

Export examples

Common export workflows

Build training datasets

Extract user corrections

Generate reports

Preserve annotations

Next steps