Large experiment downloads timeout in UI

Applies to:

Plan -
Deployment -

Summary

Issue: Downloading JSON exports for large experiments from the Braintrust UI fails with a malloc of size 1073741824 failed error or times out during the download process. Cause: The UI attempts to load the entire dataset into memory at once, causing memory allocation failures for experiments with thousands of records. Resolution: Use the Braintrust API or SDK to paginate and export large experiment data programmatically.

Resolution Steps

Pick the option that matches what you have on hand. If you copied an experiment ID out of the app URL, use Option 1 or 2. If you know the project and experiment names instead, Option 3 requires less setup.

Option 1: Export by experiment ID (Python)

Step 1: Install the API client

The REST client ships separately from the tracing SDK:

pip install braintrust-api

Step 2: Create the export script

Each fetch response returns a cursor. Pass it to the next request to walk through the experiment a page at a time.

from braintrust_api import Braintrust
import json

BRAINTRUST_API_KEY = "your-api-key"
EXPERIMENT_ID = "your-experiment-id"
CHUNK_SIZE = 200

client = Braintrust(api_key=BRAINTRUST_API_KEY)

rows = []
cursor = None

while True:
    page = client.experiments.fetch_post(
        EXPERIMENT_ID,
        limit=CHUNK_SIZE,
        cursor=cursor,
    )
    rows.extend(event.model_dump() for event in page.events)

    if not page.events or not page.cursor:
        break

    cursor = page.cursor

with open("experiment_data.json", "w") as f:
    json.dump(rows, f, indent=2, default=str)

limit caps the number of full traces per page, not the number of rows. A page containing multi-span traces will return more rows than limit.

Step 3: Run the script

Execute the script to generate experiment_data.json in your current directory.

Option 2: Export by experiment ID (TypeScript/JavaScript)

Step 1: Install the API client

npm install @braintrust/api

Step 2: Create the export script

import Braintrust from "@braintrust/api";
import fs from "fs";

const BRAINTRUST_API_KEY = "your-api-key";
const EXPERIMENT_ID = "your-experiment-id";
const CHUNK_SIZE = 200;

const client = new Braintrust({ apiKey: BRAINTRUST_API_KEY });

async function exportExperiment() {
  const allData = [];
  let cursor = undefined;

  while (true) {
    const page = await client.experiments.fetchPost(EXPERIMENT_ID, {
      limit: CHUNK_SIZE,
      cursor,
    });

    allData.push(...page.events);

    if (page.events.length === 0 || !page.cursor) break;
    cursor = page.cursor;
  }

  fs.writeFileSync("experiment_data.json", JSON.stringify(allData, null, 2));
}

exportExperiment();

Step 3: Run the script

Execute the script to generate experiment_data.json in your current directory.

Option 3: Export by experiment name (Python tracing SDK)

If you already depend on the braintrust package, open the experiment in read-only mode with open=True and iterate it. fetch() paginates internally, so there is no cursor to manage.

import braintrust
import json

exp = braintrust.init(
    project="your-project-name",
    experiment="your-experiment-name",
    open=True,
    api_key="your-api-key",
)

with open("experiment_data.json", "w") as f:
    json.dump(list(exp.fetch(batch_size=200)), f, indent=2, default=str)

open=True requires the experiment name, not its ID, and raises ValueError if the experiment does not already exist. Use Option 1 if all you have is an ID.

Option 4: Export to CSV format

Experiment events do not share a uniform set of keys, so make one paginated pass to collect the header fields, then make a second paginated pass to stream rows into the CSV. The script serializes nested values as JSON strings.

from braintrust_api import Braintrust
import csv
import json

BRAINTRUST_API_KEY = "your-api-key"
EXPERIMENT_ID = "your-experiment-id"
CHUNK_SIZE = 200

client = Braintrust(api_key=BRAINTRUST_API_KEY)

def serialize_value(value):
    if isinstance(value, (str, int, float, bool)) or value is None:
        return value

    return json.dumps(value, default=str)

def fetch_pages():
    cursor = None

    while True:
        page = client.experiments.fetch_post(
            EXPERIMENT_ID,
            limit=CHUNK_SIZE,
            cursor=cursor,
        )
        yield page.events

        if not page.events or not page.cursor:
            break

        cursor = page.cursor

fieldnames = sorted(
    {
        key
        for events in fetch_pages()
        for event in events
        for key in event.model_dump()
    }
)

with open("experiment_data.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=fieldnames)
    writer.writeheader()

    for events in fetch_pages():
        for event in events:
            writer.writerow(
                {
                    key: serialize_value(value)
                    for key, value in event.model_dump().items()
                }
            )

Additional Notes

A feature request exists to improve UI performance for large experiment downloads, including async export with email notification when ready. Until implemented, API-based exports are the recommended approach for datasets with more than 1000 records.

​Summary

​Resolution Steps

​Option 1: Export by experiment ID (Python)

​Step 1: Install the API client

​Step 2: Create the export script

​Step 3: Run the script

​Option 2: Export by experiment ID (TypeScript/JavaScript)

​Step 1: Install the API client

​Step 2: Create the export script

​Step 3: Run the script

​Option 3: Export by experiment name (Python tracing SDK)

​Option 4: Export to CSV format

​Additional Notes

Summary

Resolution Steps

Option 1: Export by experiment ID (Python)

Step 1: Install the API client

Step 2: Create the export script

Step 3: Run the script

Option 2: Export by experiment ID (TypeScript/JavaScript)

Step 1: Install the API client

Step 2: Create the export script

Step 3: Run the script

Option 3: Export by experiment name (Python tracing SDK)

Option 4: Export to CSV format

Additional Notes