> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Braintrust to Arize AX

> Import historical Braintrust logs into Arize AX with a coding-agent skill, then continue tracing in AX.

Move historical Braintrust project logs into Arize AX so past conversations land in the same workspace as your AX investigations and evaluations.

Importing history is different from pointing your app at AX for the first time. Instrumentation alone only captures **new** traffic. The migration skill copies **existing** Braintrust spans into an AX project and reshapes them for how AX groups traces and sessions.

## What you can migrate

| Migrated by the coding-agent skill | Recreate or re-run in AX |
| - | - |
| Historical project logs / spans | Scorers / experiments (re-run for now) |
| Span inputs and outputs | Old Braintrust scores as AX experiment truth |
| Parent links from `span_parents` | |
| Conversation metadata → AX sessions | |
| Datasets and examples | |
| Prompts (latest and/or versions + environments as labels) | |

Braintrust often stores an entire conversation as **one** trace. Arize groups **one trace per user turn** and links turns with `session.id`. The skill makes that conversion for you so the AX Traces and Sessions views stay usable.

## How Braintrust maps into Arize

| Braintrust | Arize AX |
| - | - |
| Conversation / `chat.session` | Session (`session.id`), not one mega-trace |
| `chat.request` (a turn) | One trace |
| Nested tool / LLM spans | Child spans under that turn |
| `output` | `output.value` as readable text |
| `metadata.session_id` | `session.id` |
| `metadata.user_id` | `user.id` when present |

## Migrate existing Braintrust data

<Steps>
  <Step title="Install the migration skill">
    ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    npx skills add Arize-ai/arize-skills --skill arize-migrate-braintrust --yes
    ```

    See [Install skills](/docs/ax/skills/install) if you need the full Arize Skills setup.
  </Step>

  <Step title="Ask your coding agent to start">
    > Use the Arize Braintrust migration skill. I want to import historical Braintrust traces into AX.

    Tell the agent your Braintrust project name and the AX space and destination project you want. Prefer a **new** AX project name so you can review the import cleanly.
  </Step>

  <Step title="Provide connection details privately">
    Give the agent credentials through a local env file path you control, or let it generate a secure command you run in a separate terminal. Do not paste API keys into agent chat.

    * Braintrust: `BRAINTRUST_API_KEY` (and `BRAINTRUST_API_URL` if you are not on the default US cloud)
    * [Create or find an AX API key](/docs/ax/security-and-settings/api-keys) and space ID for OTLP ingest
  </Step>

  <Step title="Review the plan and import">
    The agent confirms the source project, destination AX project, and import scope. Approve before it writes to AX.

    It queries Braintrust logs (BTQL), maps attributes, and ingests spans into AX over OTLP. Small projects often finish quickly; larger histories take longer while AX indexes spans.
  </Step>

  <Step title="Verify in Arize AX">
    In the destination project, open a conversation and check:

    1. **One trace per turn** — you should see multiple traces for a multi-turn chat, not a single flat tree for the whole conversation
    2. **Sessions** — those turns share the same `session.id`
    3. **Parents** — tools and model calls nest under the turn
    4. **Output** — turn and LLM spans show readable final text in `output.value`

    If the tree looks wrong, re-import into a fresh project after the agent adjusts the mapping.
  </Step>

  <Step title="Migrate prompts (optional)">
    Ask the agent to import Braintrust prompts (`GET /v1/prompt`) into the AX Prompt Hub. You can choose **latest only** or walk versions / environments.

    The agent maps `prompt_data` messages into AX roles, creates each prompt, then versions and sets labels (for example Braintrust `environment` → an AX label such as `production`).
  </Step>
</Steps>

## After you migrate

Historical import does not change where your **running app** sends new spans. When you are ready for new traffic in AX, follow [Set up tracing](/docs/ax/instrument/set-up-tracing) and [Configure your tracer](/docs/ax/instrument/configure-your-tracer).

<Note>
  Keep Braintrust available until you have verified the import, because the skill reads from the Braintrust API. See the [arize-migrate-braintrust skill source](https://github.com/Arize-ai/arize-skills/tree/main/skills/arize-migrate-braintrust) for current behavior and limits.
</Note>

## Related guides

* [Migrate from LangSmith](/docs/ax/cookbooks/migrate/migrate-from-langsmith)
* [Migrate from Langfuse](/docs/ax/cookbooks/migrate/migrate-from-langfuse)
* [Migrate from Phoenix](/docs/ax/cookbooks/migrate/migrate-from-phoenix)
* [Skill catalog](/docs/ax/skills/catalog)