Braintrust API Python Client

0.6.0 · active · verified Thu Apr 16

The `braintrust-api` library is the official Python client for interacting with the Braintrust REST API. It provides convenient access to log, trace, and evaluate AI applications. The library includes type definitions for all request parameters and response fields, supporting both synchronous and asynchronous clients. It is actively maintained with frequent updates, with the current version being 0.6.0.

Common errors

```
braintrust_api.APIStatusError: The API key is invalid or missing.
```
cause The `BRAINTRUST_API_KEY` environment variable is either not set, or the provided API key is incorrect or expired. This typically results in a 401 Unauthorized or 403 Forbidden status code.

fix Verify that `BRAINTRUST_API_KEY` is correctly set in your environment and contains a valid Braintrust API key. You can generate API keys in your Braintrust organization settings.
```
ImportError: cannot import name 'Braintrust' from 'braintrust' (unknown location)
```
cause You have likely installed the `braintrust` SDK package instead of the `braintrust-api` client library, or are trying to import `Braintrust` from the wrong top-level package.

fix Ensure you have installed `braintrust-api` (`pip install braintrust-api`) and are importing from `braintrust_api`: `from braintrust_api import Braintrust`.
```
AttributeError: 'Braintrust' object has no attribute 'create' (or similar method missing)
```
cause This usually indicates that the `Braintrust` client (or `AsyncBraintrust` client) was not properly initialized or an invalid API call was attempted. Alternatively, it might be a version mismatch where a method was removed or renamed.

fix Double-check the official documentation for the correct API client initialization and method signatures for your installed version. Ensure your client object is correctly assigned and that you are calling a valid method (e.g., `client.projects.create(...)`).

Warnings

gotcha The `braintrust-api` library (this client) is distinct from the `braintrust` SDK. They have different top-level imports and purposes (REST API access vs. AI logging/evaluation utilities). Ensure you install and import from the correct package based on your needs.
Fix: For direct REST API access, `pip install braintrust-api` and `from braintrust_api import Braintrust`. For AI logging/evaluation, `pip install braintrust` and `from braintrust import Eval` or `init_logger`.
gotcha API keys should not be hardcoded in your source code. They are sensitive credentials and should be managed securely, preferably through environment variables.
Fix: Set the `BRAINTRUST_API_KEY` environment variable (e.g., `export BRAINTRUST_API_KEY='bt_your_api_key_here'`) or use a `.env` file with `python-dotenv`.
gotcha There are separate synchronous (`Braintrust`) and asynchronous (`AsyncBraintrust`) clients. Attempting to `await` a method of the synchronous client or calling an asynchronous method without `await` will lead to runtime errors.
Fix: For async operations, import `AsyncBraintrust` and always use `await` with its methods. For sync operations, use `Braintrust` and call methods directly without `await`.

Install

pip install braintrust-api Install stable version

Imports

Braintrust
```
from braintrust_api import Braintrust
```
AsyncBraintrust
wrong:
```
from braintrust import AsyncBraintrust
```
correct:
```
from braintrust_api import AsyncBraintrust
```
The Braintrust SDK (`braintrust` package) and Braintrust API client (`braintrust-api` package) are distinct. Use `braintrust_api` for the REST API client.

Quickstart

Initializes the Braintrust API client using an API key from an environment variable and creates a new project. This demonstrates basic client initialization and a synchronous API call.

import os
from braintrust_api import Braintrust

# Ensure BRAINTRUST_API_KEY is set in your environment variables
# e.g., export BRAINTRUST_API_KEY="bt_your_api_key_here"
api_key = os.environ.get("BRAINTRUST_API_KEY")

if not api_key:
    raise ValueError("BRAINTRUST_API_KEY environment variable not set.")

client = Braintrust(api_key=api_key)

try:
    # Create a new project
    project = client.projects.create(name="My New Project")
    print(f"Created project with ID: {project.id} and Name: {project.name}")

    # Optionally, list projects
    projects_list = client.projects.list(limit=1)
    for p in projects_list.objects:
        print(f"Existing project: {p.name} ({p.id})")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →