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

# Braintrust Integration: Sync Traces into Bigspin

> Link your Braintrust account to Bigspin to automatically import experiment logs as transcripts. Filter by metadata to scope which traces each project ingests.

Connecting Braintrust to Bigspin lets you pull traces and experiment logs from your Braintrust workspace directly into Bigspin projects. Once the integration is active, you can create projects sourced from Braintrust, apply metadata filters to narrow which traces are ingested, and let Bigspin handle the rest automatically — no manual exports required.

## Connect your Braintrust account

<Steps>
  <Step title="Open Integrations settings">
    In the Bigspin dashboard, go to **Settings** > **Integrations**.
  </Step>

  <Step title="Select Braintrust">
    Click the **Braintrust** card to open the connection form.
  </Step>

  <Step title="Enter your API key">
    Paste your Braintrust API key into the field. Braintrust API keys follow the format:

    ```text theme={null}
    sk-...
    ```

    If you don't have a key yet, follow the [Braintrust authentication guide](https://www.braintrust.dev/docs/reference/api/auth) to generate one.
  </Step>

  <Step title="Validate and connect">
    Bigspin validates the key against your Braintrust account before saving. If validation succeeds, the integration appears as connected on the Integrations page.

    <Note>
      Validation happens automatically when you submit the form. Bigspin does not store your key until the check passes.
    </Note>
  </Step>
</Steps>

## Create a project with Braintrust as the data source

Once the integration is connected, you can create Bigspin projects that pull from your Braintrust workspace.

<Steps>
  <Step title="Go to Projects">
    Navigate to **Projects** in the Bigspin dashboard.
  </Step>

  <Step title="Open Data Sources">
    Click **Data Sources** when setting up a new project.
  </Step>

  <Step title="Select Braintrust">
    Choose **Braintrust** from the list of available sources.
  </Step>

  <Step title="Apply metadata filters (optional)">
    Bigspin fetches the metadata keys available in your Braintrust workspace and displays them in a filter panel. For each key you want to filter on:

    * Select the metadata key from the dropdown.
    * Choose or type the value to match. Bigspin shows sample values pulled from your workspace to help you pick the right one.
    * Review the **preview count** — Bigspin shows how many traces match your current filter combination before you finalize the project.

    <Tip>
      Use metadata filters to scope ingestion to a specific experiment, model version, or environment. Narrowing the filter set keeps your project focused and speeds up analysis.
    </Tip>

    You can add multiple key/value filters. Bigspin applies them together, ingesting only traces that match all conditions.
  </Step>

  <Step title="Finish creating the project">
    Complete the remaining project setup steps. Bigspin begins ingesting matching Braintrust traces automatically.
  </Step>
</Steps>

## Ongoing ingestion

After initial setup, Bigspin ingests traces from Braintrust automatically. You do not need to trigger syncs manually or re-export data from Braintrust.

<Note>
  If you rotate your Braintrust API key, return to **Settings** > **Integrations** and update the key so ingestion continues without interruption.
</Note>