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

# Braintrust

> Index prompts, datasets and experiments from Braintrust

The Braintrust connector indexes the prompts, datasets and experiments of your Braintrust organization,
so an evaluation result can be found from Onyx search.

## How it works

| Content     | Behavior                                                                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Prompts     | One document per prompt, named `Prompt: <name>`.                                                                                          |
| Datasets    | One document per dataset, named `Dataset: <name>`, holding its rows as a table.                                                           |
| Experiments | One document per experiment, named `Experiment: <name>`. The summary is always indexed; the per-row results depend on the lookback below. |
| Permissions | Not available. **Auto Sync Permissions** is not offered for Braintrust, so the access type can only be **Public** or **Private**.         |

Onyx indexes prompts first, then datasets, then experiments,
and keeps its place between runs so a large organization is indexed across several attempts.

A dataset or experiment table is truncated to its **10,000 most recent rows**. When that happens,
Onyx adds a line to the document saying the table was truncated, so the limit is visible in search rather than silent.

## Before you begin

You need:

* A Braintrust account with access to the organization you want to index
* A Braintrust API key
* An Onyx administrator account

<Note>
  The connector reads the Braintrust API at `https://api.braintrust.dev` and indexes only what the API key can read.
</Note>

## Configure Onyx

<Steps>
  <Step title="Open the Braintrust connector">
    In Onyx, go to **Admin Panel → Add Connector** and select **Braintrust**.
  </Step>

  <Step title="Create a credential">
    Paste the key into **Braintrust API Key**.

    <img className="rounded-image" src="https://mintcdn.com/danswer/Bny6g_G_N2tiUSbs/assets/admins/connectors/braintrust/BraintrustCredential.png?fit=max&auto=format&n=Bny6g_G_N2tiUSbs&q=85&s=00b640bda1cd9a6b9bb51c00915e92e2" alt="Create a Braintrust credential with a name and the Braintrust API key" width="1920" height="856" data-path="assets/admins/connectors/braintrust/BraintrustCredential.png" />
  </Step>

  <Step title="Choose the scope">
    Give the connector a name. In **Project Name**, enter a single Braintrust project to index only its prompts,
    datasets and experiments. Leave it empty to index the whole organization.

    Onyx checks the name when you save the connector and refuses a project it cannot find.
  </Step>

  <Step title="Choose the access type">
    **Public** makes all indexed Braintrust content visible to every Onyx user.
    **Private** limits the connector to selected Onyx user groups, and is a paid feature:
    the Business and Enterprise tiers on Onyx Cloud, and the Enterprise Edition when self-hosted.
  </Step>

  <Step title="Connect and verify">
    Select **Create Connector**. Then open **Admin Panel → Existing Connectors**, select the connector,
    and confirm its first indexing attempt completes.
  </Step>
</Steps>

### Advanced settings

| Setting                        | Default | Purpose                                                                                                                                                                    |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Experiment Row Lookback (days) | 30      | Index the per-row results only of experiments created within this many days. Experiment summaries are always indexed. Set it to `0` to index the rows of every experiment. |

Raise the lookback, or set it to `0`, when you need to search the rows of older experiments.
Both make each indexing run read more from Braintrust.

## Limits

| Limit               | Value        | Notes                                                                 |
| ------------------- | ------------ | --------------------------------------------------------------------- |
| Rows per table      | 10,000       | The most recent rows are kept and the document says it was truncated. |
| Braintrust API call | 60s          |                                                                       |
| Retries per request | 5            |                                                                       |
| Request rate        | 4 per second | Onyx throttles itself to stay within the Braintrust API's limits.     |

The connector downloads no files, so it has no file-size cap.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The API key is rejected">
    `Braintrust API rejected the API key` with HTTP 401 or 403 means the key is wrong, revoked,
    or belongs to an organization you did not intend. Create a new key in Braintrust and update the Onyx credential.
  </Accordion>

  <Accordion title="The project is not found">
    `Braintrust project '<name>' was not found` means **Project Name** does not match a project the key can read.
    The name must match exactly. Leave the field empty to index the whole organization.
  </Accordion>

  <Accordion title="Braintrust cannot be reached">
    `Failed to reach the Braintrust API` means the request did not complete.
    Check that the Onyx server can reach `https://api.braintrust.dev`, then retry.
  </Accordion>

  <Accordion title="Experiment rows are missing">
    Only experiments created within **Experiment Row Lookback (days)** have their rows indexed;
    older experiments keep their summary only. Raise the lookback, or set it to `0`, then re-index.
  </Accordion>

  <Accordion title="A large table is incomplete">
    A table stops at its 10,000 most recent rows, and the document says so. This limit is not configurable.
  </Accordion>
</AccordionGroup>