---
id: braintrust-api
version: "0.6.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# braintrust-api — The official Python library for the braintrust API

License: permissive · Maintenance: active · Downloads: 218.1K/mo

## What it is and what it does

Braintrust-api is the official Python client for the Braintrust REST API, generated using Stainless. It wraps HTTP calls to Braintrust's service with full type annotations for request parameters and response objects, enabling IDE autocomplete and type checking. The library ships both synchronous and asynchronous clients powered by httpx, so you can choose the concurrency model that fits your application.

Typical usage involves instantiating a Braintrust client with an API key, then calling methods like client.projects.create() or client.projects.list(). Responses are Pydantic models with helper methods for JSON serialization and dictionary conversion. The library handles pagination automatically via iterators, retries transient errors up to 2 times by default, and raises specific exception types (APIConnectionError, RateLimitError, APIStatusError) so you can handle failures gracefully.

Use it for:

- Build a Python application that creates and manages Braintrust projects programmatically with full type safety.
- Integrate Braintrust API calls into an async/await workflow for non-blocking I/O in concurrent applications.
- Iterate over paginated Braintrust API responses automatically without manually tracking cursors or page tokens.
- Catch and handle specific API errors (rate limits, authentication failures, timeouts) with dedicated exception types.
- Serialize Braintrust API responses to JSON or dictionaries for logging, caching, or downstream processing.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a Python client library for the Braintrust REST API with type-safe request and response handling, supporting both synchronous and asynchronous operations.

Yes. The library is actively maintained, has low install friction, carries no known vulnerabilities, and is licensed permissively. It is well-suited for any Python project that needs to interact with the Braintrust API. The main prerequisite is a valid API key and network access to Braintrust's service.

## Install

pip install braintrust-api
uv add braintrust-api
poetry add braintrust-api

## Installing braintrust-api

Before you install: Low install friction with a pure-wheel distribution and standard dependencies (httpx, pydantic, anyio). Actively maintained with recent commits and support for current Python versions (3.8–3.12).

License in practice: Apache-2.0 is permissive; you can use, modify, and distribute this library freely in commercial and open-source projects with minimal restrictions.

Quickstart:

pip install braintrust-api

import os
from braintrust_api import Braintrust

client = Braintrust(
    api_key=os.environ.get("BRAINTRUST_API_KEY"),
)

project = client.projects.create(name="foobar")
print(project.id)

Requires a valid BRAINTRUST_API_KEY environment variable or passed as an argument to authenticate with the Braintrust service.

Verify before relying:

- Whether the library's auto-retry behavior (2 times by default) and timeout handling (1 minute default) meet typical production requirements.
- Rate of API changes and backward compatibility guarantees between minor versions.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 218.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

braintrust api client, python rest api client, typed api wrapper, async http client library, api sdk python, braintrust python sdk, api-client, async-support, type-safe

[View on SkillFed](https://skillfed.io/packages/braintrust-api) · [View on PyPI](https://pypi.org/project/braintrust-api/)