Skip to main content
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

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

​
Migrate existing Braintrust data

1

Install the migration skill

See Install skills if you need the full Arize Skills setup.
2

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

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 and space ID for OTLP ingest
4

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

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

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

​
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 and Configure your tracer.
Keep Braintrust available until you have verified the import, because the skill reads from the Braintrust API. See the arize-migrate-braintrust skill source for current behavior and limits.