API Reference - Braintrust

The Braintrust API allows you to interact with all aspects of the Braintrust platform programmatically. You can use it to:

Create and manage projects, experiments, and datasets
Log traces and metrics
Manage prompts, tools, and scorers
Configure access control and permissions
Retrieve and analyze results

The API is defined by an OpenAPI specification published at braintrust-openapi on GitHub.

Base URL

The base URL depends on your organization’s data plane region:

Region	Base URL
US	`https://api.braintrust.dev`
EU	`https://api-eu.braintrust.dev`
Self-hosted	Your custom data plane URL

You can find your API URL in Settings > Data plane.

Authentication

Authenticate requests with your API key in the Authorization header:

curl https://api.braintrust.dev/v1/project \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY"

Create API keys in Settings > API keys.

SDKs

While you can call the API directly, we recommend using one of our official SDKs:

TypeScript SDK

Official TypeScript/JavaScript SDK

Python SDK

Official Python SDK

Go SDK

Official Go SDK

Ruby SDK

Official Ruby SDK

Java SDK

Official Java SDK

C# SDK

Official C# SDK

Kotlin SDK

Official Kotlin SDK

API resources

The API is organized around REST principles. Each resource has predictable URLs and uses HTTP response codes to indicate API errors. Project resources

Projects: Organize your AI features and experiments
Experiments: Run and track evaluation experiments
Datasets: Manage test data for evaluations
Logs: Store and query production traces
Prompts: Version control your prompts
Functions: Manage tools, scorers, and workflows
Evals: Configure and run evaluations
Scores: Define custom scoring functions
Tags: Organize and filter project resources
Automations: Configure automated workflows
Views: Create and manage custom data views

Organization resources

Organizations: Manage your organization settings
Users: Manage team members
Groups: Organize users into teams
Roles: Define permission levels
ACLs: Configure fine-grained access control
API keys: Manage authentication credentials
Service tokens: Generate service-level authentication tokens

Configuration resources

AI secrets: Securely store API keys and credentials
Environment variables: Manage environment-specific configuration
MCP servers: Configure Model Context Protocol servers
Proxy: Configure proxy settings for API requests

Response format

All API responses are returned in JSON format. Successful responses will have a 2xx status code, while errors will return 4xx or 5xx status codes with error details.

Rate limits

The API uses rate limiting to ensure fair usage. Rate limits are applied per organization and endpoint. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Query data

Query your logs, experiments, and datasets with SQL through the /btql endpoint.

Query logs and experiments

Use the /btql endpoint to query data with SQL syntax. Data-source functions like project_logs() and experiment() accept an object name or its ID. See Querying by name for details. To control query lint warnings, set the lint_mode parameter — see Lint warnings.

const API_URL = "https://api.braintrust.dev/";
const headers = {
  Authorization: `Bearer ${process.env.BRAINTRUST_API_KEY}`,
};

const query = `
  SELECT id, input, output, scores
  FROM project_logs('your-project-id', shape => 'traces')
  WHERE scores.accuracy > 0.8
  LIMIT 100
`;

const response = await fetch(`${API_URL}/btql`, {
  method: "POST",
  headers,
  body: JSON.stringify({ query, fmt: "json" }),
});

const data = await response.json();
for (const row of data.data) {
  console.log(row);
}

import os
import requests

API_URL = "https://api.braintrust.dev/"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

query = """
SELECT id, input, output, scores
FROM project_logs('your-project-id', shape => 'traces')
WHERE scores.accuracy > 0.8
LIMIT 100
"""

response = requests.post(
    f"{API_URL}/btql",
    headers=headers,
    json={"query": query, "fmt": "json"},
).json()

for row in response["data"]:
    print(row)

Filter experiments by metadata

Filter experiments by metadata field equality using the metadata query parameter on GET /v1/experiment. Pass a JSON-serialized object to match experiments where all specified fields are equal — including nested paths:

import json
import os
import requests

API_URL = "https://api.braintrust.dev/v1"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

response = requests.get(
    f"{API_URL}/experiment",
    headers=headers,
    params=dict(
        project_id="your-project-id",
        metadata=json.dumps({"env": "production", "model": {"name": "gpt-5-mini"}}),
    ),
)

experiments = response.json().get("objects", [])
for experiment in experiments:
    print(experiment["id"], experiment["name"])

const API_URL = "https://api.braintrust.dev/v1";
const headers = {
  Authorization: `Bearer ${process.env.BRAINTRUST_API_KEY}`,
};

const params = new URLSearchParams({
  project_id: "your-project-id",
  metadata: JSON.stringify({ env: "production", model: { name: "gpt-5-mini" } }),
});

const response = await fetch(`${API_URL}/experiment?${params}`, { headers });
const { objects: experiments } = await response.json();
for (const experiment of experiments) {
  console.log(experiment.id, experiment.name);
}

Fetch experiment results

Query experiments to check review status or other metrics:

import os
import requests

API_URL = "https://api.braintrust.dev/"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

def fetch_experiment_review_status(experiment_id: str) -> dict:
    # Replace "response quality" with the name of your review score column
    query = f"""
    SELECT
      sum(CASE WHEN scores."response quality" IS NOT NULL THEN 1 ELSE 0 END) AS reviewed,
      sum(CASE WHEN is_root THEN 1 ELSE 0 END) AS total
    FROM experiment('{experiment_id}')
    """

    return requests.post(
        f"{API_URL}/btql",
        headers=headers,
        json={"query": query, "fmt": "json"},
    ).json()

EXPERIMENT_ID = "your-experiment-id"
print(fetch_experiment_review_status(EXPERIMENT_ID))

Fetch child spans by trace metadata

Retrieve specific child spans based on trace-level metadata:

import os
import requests

API_URL = "https://api.braintrust.dev/"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

PROJECT_ID = "your-project-id"
SPAN_NAME = "root"  # or any specific span name

# Find all rows matching a certain metadata value
query = f"""
SELECT span_attributes, metrics
FROM project_logs('{PROJECT_ID}', shape => 'traces')
WHERE metadata.orgName = 'qawolf'
LIMIT 10
"""

response = requests.post(f"{API_URL}/btql", headers=headers, json={"query": query}).json()

durations = []
for trace in response["data"]:
    if trace["span_attributes"]["name"] == SPAN_NAME:
        metrics = trace["metrics"]
        if metrics.get("end") and metrics.get("start"):
            duration = metrics["end"] - metrics["start"]
            durations.append(duration)
            print(f"Duration: {duration}ms")
        else:
            print("Start or end not found for this span")

if durations:
    print(f"\nAverage duration: {sum(durations) / len(durations)}ms")

Export data

Export logs, experiments, or datasets to JSON or Parquet:

# Export to JSON
curl https://api.braintrust.dev/btql \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM project_logs(\"project-id\") traces",
    "fmt": "json"
  }' > export.json

# Export to Parquet
curl https://api.braintrust.dev/btql \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM project_logs(\"project-id\") traces",
    "fmt": "parquet"
  }' > export.parquet

import os
import requests

API_URL = "https://api.braintrust.dev/"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

query = """
SELECT *
FROM project_logs('your-project-id', shape => 'traces')
WHERE created >= now() - interval '7 days'
"""

# JSON format
response = requests.post(
    f"{API_URL}/btql",
    headers=headers,
    json={"query": query, "fmt": "json"},
).json()

# Parquet format (returns binary data)
response = requests.post(
    f"{API_URL}/btql",
    headers=headers,
    json={"query": query, "fmt": "parquet"},
)
with open("export.parquet", "wb") as f:
    f.write(response.content)

Paginate large datasets

If you’re using the Python or TypeScript SDK, pagination is handled automatically. Only use this code if you’re developing with other tools.

For large datasets, paginate using cursors:

// If you're self-hosting Braintrust, then use your stack's Universal API URL, e.g.
//   https://dfwhllz61x709.cloudfront.net
export const BRAINTRUST_API_URL = "https://api.braintrust.dev";
export const API_KEY = process.env.BRAINTRUST_API_KEY;

export async function* paginateDataset(args: {
  project: string;
  dataset: string;
  version?: string;
  // Number of rows to fetch per request. You can adjust this to be a lower number
  // if your rows are very large (e.g. several MB each).
  perRequestLimit?: number;
}) {
  const { project, dataset, version, perRequestLimit } = args;
  const headers = {
    Accept: "application/json",
    "Accept-Encoding": "gzip",
    Authorization: `Bearer ${API_KEY}`,
  };
  const fullURL = `${BRAINTRUST_API_URL}/v1/dataset?project_name=${encodeURIComponent(
    project,
  )}&dataset_name=${encodeURIComponent(dataset)}`;
  const ds = await fetch(fullURL, {
    method: "GET",
    headers,
  });
  if (!ds.ok) {
    throw new Error(
      `Error fetching dataset metadata: ${ds.status}: ${await ds.text()}`,
    );
  }
  const dsJSON = await ds.json();
  const dsMetadata = dsJSON.objects[0];
  if (!dsMetadata?.id) {
    throw new Error(`Dataset not found: ${project}/${dataset}`);
  }

  let cursor: string | null = null;
  while (true) {
    const body: string = JSON.stringify({
      query: {
        from: {
          op: "function",
          name: { op: "ident", name: ["dataset"] },
          args: [{ op: "literal", value: dsMetadata.id }],
        },
        select: [{ op: "star" }],
        limit: perRequestLimit,
        cursor,
      },
      fmt: "jsonl",
      version,
    });
    const response = await fetch(`${BRAINTRUST_API_URL}/btql`, {
      method: "POST",
      headers,
      body,
    });
    if (!response.ok) {
      throw new Error(
        `Error fetching rows for ${dataset}: ${
          response.status
        }: ${await response.text()}`,
      );
    }

    cursor =
      response.headers.get("x-bt-cursor") ??
      response.headers.get("x-amz-meta-bt_cursor");

    // Parse jsonl line-by-line
    const allRows = await response.text();
    const rows = allRows.split("\n");
    let rowCount = 0;
    for (const row of rows) {
      if (!row.trim()) {
        continue;
      }
      yield JSON.parse(row);
      rowCount++;
    }

    if (rowCount === 0) {
      break;
    }
  }
}

async function main() {
  for await (const row of paginateDataset({
    project: "Your project name", // Replace with your project name
    dataset: "Your dataset name", // Replace with your dataset name
    perRequestLimit: 100,
  })) {
    console.log(row);
  }
}

main();

Write and manage data

Run experiments

Create and run experiments programmatically:

import os
from uuid import uuid4
import requests

API_URL = "https://api.braintrust.dev/v1"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

# Create a project
project = requests.post(
    f"{API_URL}/project",
    headers=headers,
    json={"name": "My Project"}
).json()

# Create an experiment
experiment = requests.post(
    f"{API_URL}/experiment",
    headers=headers,
    json={"name": "Test Run", "project_id": project["id"]}
).json()

# Insert experiment results
for i in range(10):
    requests.post(
        f"{API_URL}/experiment/{experiment['id']}/insert",
        headers=headers,
        json={
            "events": [{
                "id": uuid4().hex,
                "input": {"question": f"Test {i}"},
                "output": f"Answer {i}",
                "scores": {"accuracy": 0.9}
            }]
        }
    )

Log programmatically

Insert logs via the API:

import os
from uuid import uuid4
import requests

API_URL = "https://api.braintrust.dev/v1"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

# Get or create project
project = requests.post(
    f"{API_URL}/project",
    headers=headers,
    json={"name": "My Project"}
).json()

# Insert log event
requests.post(
    f"{API_URL}/project_logs/{project['id']}/insert",
    headers=headers,
    json={
        "events": [{
            "id": uuid4().hex,
            "input": {"question": "What is 2+2?"},
            "output": "4",
            "scores": {"accuracy": 1.0},
            "metadata": {"environment": "production"}
        }]
    }
)

Delete logs

Mark logs for deletion by setting _object_delete:

import os
import requests

API_URL = "https://api.braintrust.dev/"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

# Find logs to delete
query = """
SELECT id
FROM project_logs('project-id', shape => 'traces')
WHERE metadata.user_id = 'test-user'
"""

response = requests.post(
    f"{API_URL}/btql",
    headers=headers,
    json={"query": query}
).json()

ids = [row["id"] for row in response["data"]]

# Delete logs
delete_events = [{"id": id, "_object_delete": True} for id in ids]
requests.post(
    f"{API_URL}/v1/project_logs/project-id/insert",
    headers=headers,
    json={"events": delete_events}
)

Impersonate users

User impersonation lets a privileged user perform an operation on behalf of another user, using the impersonated user’s identity and permissions. For example, a proxy service can forward requests from individual users to Braintrust without each user supplying their own credentials: the service authenticates with its own key and names the user to impersonate, and Braintrust runs the operation as that user. Braintrust requires that:

The requesting user has the Owner role over all organizations the impersonated user belongs to.
The impersonated user belongs to at least one organization.

Together, these requirements guarantee the requesting user has at least the set of permissions that the impersonated user has. To impersonate a user, set the x-bt-impersonate-user header to the ID or email of the user you want to impersonate. The examples below show how to configure ACLs and make a request using user impersonation:

// If you're self-hosting Braintrust, then use your stack's Universal API URL, e.g.
//   https://dfwhllz61x709.cloudfront.net
export const BRAINTRUST_API_URL = "https://api.braintrust.dev";
export const API_KEY = process.env.BRAINTRUST_API_KEY;

async function getOwnerRoleId() {
  const roleResp = await fetch(
    `${BRAINTRUST_API_URL}/v1/role?${new URLSearchParams({ role_name: "Owner" })}`,
    {
      method: "GET",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
      },
    },
  );
  if (!roleResp.ok) {
    throw new Error(await roleResp.text());
  }
  const roles = await roleResp.json();
  return roles.objects[0].id;
}

async function getUserOrgInfo(orgName: string): Promise<{
  user_id: string;
  org_id: string;
}> {
  const meResp = await fetch(`${BRAINTRUST_API_URL}/api/self/me`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  });
  if (!meResp.ok) {
    throw new Error(await meResp.text());
  }
  const meInfo = await meResp.json();
  const orgInfo = meInfo.organizations.find(
    (x: { name: string }) => x.name === orgName,
  );
  if (!orgInfo) {
    throw new Error(`No organization found with name ${orgName}`);
  }
  return { user_id: meInfo.id, org_id: orgInfo.id };
}

async function grantOwnershipRole(orgName: string) {
  const ownerRoleId = await getOwnerRoleId();
  const { user_id, org_id } = await getUserOrgInfo(orgName);

  // Grant an 'Owner' ACL to the requesting user on the organization. Granting
  // this ACL requires the user to have `create_acls` permission on the org, which
  // means they must already be an owner of the org indirectly.
  const aclResp = await fetch(`${BRAINTRUST_API_URL}/v1/acl`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      object_type: "organization",
      object_id: org_id,
      user_id,
      role_id: ownerRoleId,
    }),
  });
  if (!aclResp.ok) {
    throw new Error(await aclResp.text());
  }
}

async function main() {
  if (!process.env.ORG_NAME || !process.env.USER_EMAIL) {
    throw new Error("Must specify ORG_NAME and USER_EMAIL");
  }

  // This only needs to be done once.
  await grantOwnershipRole(process.env.ORG_NAME);

  // This will only succeed if the user being impersonated has permissions to
  // create a project within the org.
  const projectResp = await fetch(`${BRAINTRUST_API_URL}/v1/project`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "x-bt-impersonate-user": process.env.USER_EMAIL,
    },
    body: JSON.stringify({
      name: "my-project",
      org_name: process.env.ORG_NAME,
    }),
  });
  if (!projectResp.ok) {
    throw new Error(await projectResp.text());
  }
  console.log(await projectResp.json());
}

main();

import os
import requests

# If you're self-hosting Braintrust, then use your stack's Universal API URL, e.g.
# https://dfwhllz61x709.cloudfront.net
BRAINTRUST_API_URL = "https://api.braintrust.dev"
API_KEY = os.environ["BRAINTRUST_API_KEY"]

def get_owner_role_id():
    resp = requests.get(
        f"{BRAINTRUST_API_URL}/v1/role",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=dict(role_name="Owner"),
    )
    resp.raise_for_status()
    return resp.json()["objects"][0]["id"]

def get_user_org_info(org_name):
    resp = requests.post(
        f"{BRAINTRUST_API_URL}/api/self/me",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    resp.raise_for_status()
    me_info = resp.json()
    org_info = [x for x in me_info["organizations"] if x["name"] == org_name]
    if not org_info:
        raise Exception(f"No organization found with name {org_name}")
    return dict(user_id=me_info["id"], org_id=org_info[0]["id"])

def grant_ownership_role(org_name):
    owner_role_id = get_owner_role_id()
    user_org_info = get_user_org_info(org_name)

    # Grant an 'Owner' ACL to the requesting user on the organization. Granting
    # this ACL requires the user to have `create_acls` permission on the org,
    # which means they must already be an owner of the org indirectly.
    resp = requests.post(
        f"{BRAINTRUST_API_URL}/v1/acl",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=dict(
            object_type="organization",
            object_id=user_org_info["org_id"],
            user_id=user_org_info["user_id"],
            role_id=owner_role_id,
        ),
    )
    resp.raise_for_status()

def main():
    # This only needs to be done once.
    grant_ownership_role(os.environ["ORG_NAME"])

    # This will only succeed if the user being impersonated has permissions to
    # create a project within the org.
    resp = requests.post(
        f"{BRAINTRUST_API_URL}/v1/project",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "x-bt-impersonate-user": os.environ["USER_EMAIL"],
        },
        json=dict(
            name="my-project",
            org_name=os.environ["ORG_NAME"],
        ),
    )
    resp.raise_for_status()
    print(resp.json())

if __name__ == "__main__":
    main()

Next steps

Explore the complete API reference for all available endpoints
Learn about SQL querying to analyze your data
Review system limits for API usage constraints
Check out the Python SDK or TypeScript SDK documentation

Support

Need help with the API?

Join our Discord community
Email us at support@braintrust.dev

​Base URL

​Authentication

​SDKs

TypeScript SDK

Python SDK

Go SDK

Ruby SDK

Java SDK

C# SDK

Kotlin SDK

​API resources

​Response format

​Rate limits

​Query data

​Query logs and experiments

​Filter experiments by metadata

​Fetch experiment results

​Fetch child spans by trace metadata

​Export data

​Paginate large datasets

​Write and manage data

​Run experiments

​Log programmatically

​Delete logs

​Impersonate users

​Next steps

​Support

Base URL

Authentication

SDKs

API resources

Response format

Rate limits

Query data

Query logs and experiments

Filter experiments by metadata

Fetch experiment results

Fetch child spans by trace metadata

Export data

Paginate large datasets

Write and manage data

Run experiments

Log programmatically

Delete logs

Impersonate users

Next steps

Support