> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API Reference
> Complete API reference for the Braintrust API
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](https://github.com/braintrustdata/braintrust-openapi) on GitHub.
## Base URL
The base URL depends on your organization's [data plane region](/admin/organizations#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**](https://www.braintrust.dev/app/~/configuration/org/api-url).
## Authentication
Authenticate requests with your API key in the Authorization header:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl https://api.braintrust.dev/v1/project \
-H "Authorization: Bearer $BRAINTRUST_API_KEY"
```
Create API keys in [Settings > API keys](https://www.braintrust.dev/app/settings?subroute=api-keys).
## SDKs
While you can call the API directly, we recommend using one of our official SDKs:
Official TypeScript/JavaScript SDK
Official Python SDK
Official Go SDK
Official Ruby SDK
Official Java SDK
Official C# 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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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**
```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
"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](/reference/sql). To control query lint warnings, set the lint\_mode parameter — see [Lint warnings](/reference/sql/best-practices#lint-warnings).
```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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);
}
```
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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`](/api-reference/experiments/get-experiment). Pass a JSON-serialized object to match experiments where all specified fields are equal — including nested paths:
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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"])
```
```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 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
```
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
// 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();
```
### Run experiments
Create and run experiments programmatically:
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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`:
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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 allows a privileged user to perform an operation on behalf of another user, using the impersonated user's identity and permissions. For example, a proxy service may wish to forward requests coming in from individual users to Braintrust without requiring each user to directly specify Braintrust credentials. The privileged service can initiate the request with its own credentials and impersonate the user so that Braintrust runs the operation with the user's permissions.
To impersonate a user, set the `x-bt-impersonate-user` header to the ID or email of the user to impersonate. Currently impersonating another user requires that the requesting user has specifically been granted the `Owner` role over all organizations that the impersonated user belongs to. This check guarantees the requesting user has at least the set of permissions that the impersonated user has.
The following examples show how to configure ACLs and run a request with user impersonation:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
// 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();
```
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](/api-reference) for all available endpoints
* Learn about [SQL querying](/reference/sql) to analyze your data
* Review [system limits](/plans-and-limits) for API usage constraints
* Check out the [Python SDK](/sdks/python/versions/latest) or [TypeScript SDK](/sdks/typescript/versions/latest) documentation
## Support
Need help with the API?
* Join our [Discord community](https://discord.gg/6G8s47F44X)
* Email us at [support@braintrust.dev](mailto:support@braintrust.dev)