> ## 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.

# bt sync

> Sync Braintrust logs, experiments, and datasets to and from local NDJSON files

`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`

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 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

| Flag                  | Env var           | Description                                           |
| --------------------- | ----------------- | ----------------------------------------------------- |
| `--window <DURATION>` | `BT_SYNC_WINDOW`  | Time window (default: `3d`; e.g. `1h`, `7d`)          |
| `--filter <EXPR>`     |                   | BTQL filter expression                                |
| `--traces <N>`        |                   | Max root traces to fetch                              |
| `--spans <N>`         |                   | Max spans to fetch                                    |
| `--fresh`             |                   | Ignore previous state, start over                     |
| `--root <PATH>`       |                   | Output directory (default: `bt-sync`)                 |
| `--workers <N>`       |                   | Concurrent fetch workers                              |
| `--include-vectors`   |                   | Include embeddings (needed for re-ingestion via push) |
| `--verbose`           | `BT_SYNC_VERBOSE` | Print BTQL queries and timing                         |

## Push flags

| Flag            | Description                                              |
| --------------- | -------------------------------------------------------- |
| `--in <PATH>`   | Input file or directory (defaults to latest pull output) |
| `--traces <N>`  | Upload at most N root traces                             |
| `--spans <N>`   | Upload at most N span rows                               |
| `--workers <N>` | Concurrent upload workers                                |