{"id":8883,"library":"braintrust-api","title":"Braintrust API Python Client","description":"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.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/braintrustdata/braintrust-api-py","tags":["AI observability","LLM evaluation","API client","tracing","machine learning"],"install":[{"cmd":"pip install braintrust-api","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.8 or higher.","package":"Python","optional":false}],"imports":[{"symbol":"Braintrust","correct":"from braintrust_api import Braintrust"},{"note":"The Braintrust SDK (`braintrust` package) and Braintrust API client (`braintrust-api` package) are distinct. Use `braintrust_api` for the REST API client.","wrong":"from braintrust import AsyncBraintrust","symbol":"AsyncBraintrust","correct":"from braintrust_api import AsyncBraintrust"}],"quickstart":{"code":"import os\nfrom braintrust_api import Braintrust\n\n# Ensure BRAINTRUST_API_KEY is set in your environment variables\n# e.g., export BRAINTRUST_API_KEY=\"bt_your_api_key_here\"\napi_key = os.environ.get(\"BRAINTRUST_API_KEY\")\n\nif not api_key:\n    raise ValueError(\"BRAINTRUST_API_KEY environment variable not set.\")\n\nclient = Braintrust(api_key=api_key)\n\ntry:\n    # Create a new project\n    project = client.projects.create(name=\"My New Project\")\n    print(f\"Created project with ID: {project.id} and Name: {project.name}\")\n\n    # Optionally, list projects\n    projects_list = client.projects.list(limit=1)\n    for p in projects_list.objects:\n        print(f\"Existing project: {p.name} ({p.id})\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"API keys should not be hardcoded in your source code. They are sensitive credentials and should be managed securely, preferably through environment variables.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For async operations, import `AsyncBraintrust` and always use `await` with its methods. For sync operations, use `Braintrust` and call methods directly without `await`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"braintrust_api.APIStatusError: The API key is invalid or missing."},{"fix":"Ensure you have installed `braintrust-api` (`pip install braintrust-api`) and are importing from `braintrust_api`: `from braintrust_api import Braintrust`.","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.","error":"ImportError: cannot import name 'Braintrust' from 'braintrust' (unknown location)"},{"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(...)`).","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.","error":"AttributeError: 'Braintrust' object has no attribute 'create' (or similar method missing)"}]}