Documentation Index
Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
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"
}'
fmt parameter:
json (default): Returns data as JSON for easy processingparquet: Returns data in Parquet format for data warehouses and analytics tools
Export parameters
query (required): Your SQL query selecting the data to exportfmt: Response format (json or parquet)tz_offset: Timezone offset in minutes for correct timestampsaudit_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"
}'
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"
}'
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
