Skip to main content
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

​
Base URL

The API is hosted globally at: 
https://api.braintrust.dev

​
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.

​
Common tasks

​
Invoke functions

Call prompts, tools, or scorers via the /v1/function endpoint: 
curl https://api.braintrust.dev/v1/function \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -d '{
    "project_name": "My Project",
    "slug": "summarizer",
    "input": {
      "text": "Long text to summarize..."
    }
  }'
Parameters
  • project_name or project_id: Project containing the function
  • slug: Function slug
  • input: Function input parameters
  • version (optional): Pin to a specific version
  • environment (optional): Use environment-specific version
  • stream (optional): Enable streaming responses
Response 
{
  "output": "Summarized text here...",
  "metadata": {
    "model": "claude-3-5-sonnet-latest",
    "tokens": 150,
    "latency": 0.85
  }
}

​
Query logs and experiments

Use the /btql endpoint to query data with SQL syntax: 
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);
}

​
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

​
Paginate large datasets

For large datasets, paginate using cursors: 
const API_URL = "https://api.braintrust.dev/";
const headers = {
  Authorization: `Bearer ${process.env.BRAINTRUST_API_KEY}`,
};

async function* paginateDataset(projectName: string, datasetName: string) {
  // Get dataset ID
  const dsResp = await fetch(
    `${API_URL}/v1/dataset?project_name=${projectName}&dataset_name=${datasetName}`,
    { headers }
  );
  const ds = await dsResp.json();
  const datasetId = ds.objects[0].id;

  let cursor = null;
  while (true) {
    const response = await fetch(`${API_URL}/btql`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        query: {
          from: {
            op: "function",
            name: { op: "ident", name: ["dataset"] },
            args: [{ op: "literal", value: datasetId }],
          },
          select: [{ op: "star" }],
          limit: 100,
          cursor,
        },
        fmt: "jsonl",
      }),
    });

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

    const text = await response.text();
    const rows = text.split("\n").filter((r) => r.trim());

    if (rows.length === 0) break;

    for (const row of rows) {
      yield JSON.parse(row);
    }
  }
}

// Usage
for await (const row of paginateDataset("My Project", "My Dataset")) {
  console.log(row);
}

​
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

Perform operations on behalf of other users with the x-bt-impersonate-user header: 
curl https://api.braintrust.dev/v1/project \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "x-bt-impersonate-user: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Project",
    "org_name": "My Organization"
  }'
Impersonation requires the requesting user to have Owner role over all organizations the impersonated user belongs to.

​
Next steps

​
Support

Need help with the API?