Skip to main content
bt sync downloads Braintrust data to local NDJSON files and uploads it back. Use it for offline analysis, backup, or migrating data between projects and orgs. Object ref format: object_type:name_or_id Supported object types: project_logs, experiment, dataset 
# Pull the last 24 hours of logs to ./bt-sync/
bt sync pull project_logs:my-project --window 24h

# Pull a specific experiment
bt sync pull experiment:my-experiment --project my-project

# Push local files back to Braintrust
bt sync push project_logs:my-project --in bt-sync/project_logs

# Check local sync state
bt sync status project_logs:my-project

​
Pull flags

FlagEnv varDescription
--window <DURATION>BT_SYNC_WINDOWTime window (default: 3d; e.g. 1h, 7d)
--filter <EXPR>SQL filter expression
--traces <N>Max root traces to fetch
--spans <N>Max spans to fetch
--page-size <N>SQL pagination page size (default: 1000)
--cursor <CURSOR>Initial cursor for spans mode (implies a fresh run)
--freshIgnore previous state, start over
--root <PATH>Output directory (default: bt-sync)
--workers <N>Concurrent fetch workers
--include-vectorsInclude embeddings (needed for re-ingestion via push)
--verbose / -vBRAINTRUST_VERBOSEPrint SQL queries and timing

​
Push flags

FlagEnv varDescription
--in <PATH>Input file or directory (defaults to latest pull output)
--filter <EXPR>SQL filter expression (used in spec hashing and pull auto-resolution)
--traces <N>Upload at most N distinct root traces
--spans <N>Upload at most N span rows
--page-size <N>Rows per upload batch (default: 1000)
--freshIgnore previous state, start over
--root <PATH>Root directory for sync artifacts (default: bt-sync)
--workers <N>Concurrent upload workers
--max-batch-bytes <N>BT_SYNC_PUSH_MAX_BATCH_BYTESMaximum input bytes per upload batch (default: 16777216)
--max-in-flight-bytes <N>BT_SYNC_PUSH_MAX_IN_FLIGHT_BYTESMaximum input bytes held by in-flight upload batches (default: 134217728)