---
canonical_url: "https://docs.composio.dev/toolkits/braintrust"
markdown_url: "https://docs.composio.dev/toolkits/braintrust.md"
product: "platform"
version: null
last_updated: null
---

# Braintrust

Braintrust is an AI engineering platform for managing prompts, datasets, experiments, evaluations, observability, and production AI applications.

- **Category:** artificial intelligence
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 17
- **Triggers:** 0
- **Slug:** `BRAINTRUST`
- **Version:** 20260826_00

## Tools

### Create Dataset

**Slug:** `BRAINTRUST_CREATE_DATASET`

Create a named dataset under a Braintrust project, or return the existing dataset unchanged when its name already exists in that project.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Dataset name, which must be unique within the project. Braintrust returns the existing dataset unchanged when this name already exists. |
| `tags` | array | No | Tags to attach to the dataset. |
| `metadata` | object | No | User-controlled dataset metadata as an object. |
| `project_id` | string | Yes | UUID of the Braintrust project that will contain the dataset. |
| `description` | string | No | Optional human-readable dataset description. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Experiment

**Slug:** `BRAINTRUST_CREATE_EXPERIMENT`

Create an experiment under a Braintrust project. When its name already exists, Braintrust returns the existing experiment unchanged unless ensure_new is true, which creates an experiment with a unique name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Experiment name. Names are unique within a project unless ensure_new is true. |
| `tags` | array | No | Tags to attach to the experiment. |
| `public` | boolean | No | Whether anyone inside or outside the organization can view the experiment. |
| `metadata` | object | No | User-controlled experiment metadata as an object. |
| `dataset_id` | string | No | UUID of the dataset linked to this experiment, when applicable. |
| `ensure_new` | boolean | No | Generate a unique experiment name on a name conflict. When false, Braintrust returns the existing same-name experiment unchanged. |
| `project_id` | string | Yes | UUID of the Braintrust project that will contain the experiment. |
| `description` | string | No | Optional human-readable experiment description. |
| `dataset_version` | string | No | Version of the linked dataset used for reproducibility. |
| `base_experiment_id` | string | No | UUID of the default baseline experiment used for comparisons. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Project

**Slug:** `BRAINTRUST_CREATE_PROJECT`

Create a Braintrust project, or return the existing project unchanged when its name already exists.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Project name. Braintrust returns an existing project unchanged when this name already exists, so use a unique name when a new project is required. |
| `org_name` | string | No | Organization name for the rare case where the API key's active data plane supports organization selection. This does not reliably switch organizations. |
| `description` | string | No | Optional human-readable project description. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Prompt

**Slug:** `BRAINTRUST_CREATE_PROMPT`

Upsert a versioned prompt configuration under a Braintrust project without invoking it. The same project and slug reuse the prompt ID but create a new version that replaces the stored prompt configuration with the submitted configuration. MCP attachments and tool-function bindings are unsupported.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Human-readable prompt name. |
| `slug` | string | Yes | Prompt identity slug within the project. Reusing the same project and slug keeps the prompt ID but creates a new version that replaces the stored prompt configuration with the submitted configuration. |
| `tags` | array | No | Tags to attach to the prompt. |
| `project_id` | string | Yes | UUID of the Braintrust project that will contain the prompt. |
| `description` | string | No | Optional human-readable prompt description. |
| `prompt_data` | object | No | Structured prompt block, model options, and parser configuration. MCP attachments and tool_functions are rejected by this schema. |
| `function_type` | string ("llm" | "scorer" | "task" | "tool" | "custom_view" | "preprocessor" | "facet" | "classifier" | "tag" | "parameters" | "sandbox") | No | Braintrust function classification assigned to the prompt. |
| `template_format` | string ("mustache" | "nunjucks" | "none") | No | Template syntax to store inside prompt_data. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Project

**Slug:** `BRAINTRUST_DELETE_PROJECT`

Soft-delete a Braintrust project and return its deletion state.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | UUID of the Braintrust project to soft-delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Experiment, Dataset, or Prompt

**Slug:** `BRAINTRUST_DELETE_RESOURCE`

Delete one Braintrust experiment, dataset, or prompt by UUID for explicit lifecycle cleanup.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_id` | string | Yes | UUID of the selected resource to delete. |
| `resource_type` | string ("experiment" | "dataset" | "prompt") | Yes | Kind of Braintrust resource to delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Fetch Events

**Slug:** `BRAINTRUST_FETCH_EVENTS`

Fetch one newest-to-oldest page of project log, experiment, or dataset events.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum full traces to request. A page can contain more events because one trace may contain multiple events. |
| `version` | string | No | Optional historical transaction version snapshot to fetch. |
| `next_cursor` | string | No | Opaque continuation token returned by a previous call. Omit it for the first page and pass it back unchanged to continue newest-to-oldest. |
| `resource_id` | string | Yes | Project, experiment, or dataset UUID matching resource_type. |
| `resource_type` | string ("project_logs" | "experiment" | "dataset") | Yes | Event stream to fetch. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Braintrust Resource

**Slug:** `BRAINTRUST_GET_RESOURCE`

Get one project, experiment, dataset, prompt, or function by UUID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_id` | string | Yes | UUID of the selected Braintrust resource. |
| `resource_type` | string ("project" | "experiment" | "dataset" | "prompt" | "function") | Yes | Kind of Braintrust resource to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Insert Dataset Events

**Slug:** `BRAINTRUST_INSERT_DATASET_EVENTS`

Upsert a batch of examples into an existing Braintrust dataset. New or omitted IDs insert events; an existing supplied ID replaces that event's current values.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `events` | array | Yes | Dataset examples to upsert, in the order represented by returned row IDs. An event with an existing supplied ID replaces that event's current values. |
| `dataset_id` | string | Yes | UUID of the Braintrust dataset that will receive the examples. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Insert Experiment Events

**Slug:** `BRAINTRUST_INSERT_EXPERIMENT_EVENTS`

Upsert a batch of result events into an existing Braintrust experiment. New or omitted IDs insert events; an existing supplied ID replaces that event's current values.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `events` | array | Yes | Experiment result events to upsert. Row IDs in the response align with this list in the same order. An event with an existing supplied ID replaces that event's current values. |
| `experiment_id` | string | Yes | UUID of the Braintrust experiment that will receive the events. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Braintrust Resources

**Slug:** `BRAINTRUST_LIST_RESOURCES`

List and filter one page of projects, experiments, datasets, prompts, or functions visible to the connected Braintrust API key.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | array | No | Restrict results to these resource UUIDs. |
| `name` | string | No | Exact resource name to match for the selected resource type. |
| `slug` | string | No | Restrict prompts or functions to this slug. |
| `limit` | integer | No | Maximum number of objects to request in this page. |
| `version` | string | No | Restrict prompts or functions to this version identifier. |
| `org_name` | string | No | Optional organization-name filter. It does not switch the API key's active data-plane organization. |
| `project_id` | string | No | Restrict experiments, datasets, prompts, or functions to this project UUID. |
| `environment` | string | No | Restrict prompts or functions to this environment slug. |
| `next_cursor` | string | No | Opaque continuation token returned by a previous call. Omit for the first page and pass it back unchanged to continue. |
| `project_name` | string | No | Restrict experiments, datasets, prompts, or functions to this project name. |
| `resource_type` | string ("project" | "experiment" | "dataset" | "prompt" | "function") | Yes | Kind of Braintrust resource to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Query Braintrust Data

**Slug:** `BRAINTRUST_QUERY_DATA`

Run one bounded synchronous read-only BTQL query over Braintrust project logs, an experiment, or a dataset. The first-page query must end with a positive LIMIT; continue later pages by passing the returned next_cursor unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | Read-only BTQL SELECT query. It must query project_logs(...), experiment(...), or dataset(...) and end with an explicit positive LIMIT. Required on the first page; omit it when passing next_cursor. |
| `version` | string | No | Optional historical data version for a reproducible query. |
| `lint_mode` | string ("default" | "strict") | No | Braintrust query linting mode. |
| `tz_offset` | number | No | Optional timezone offset in minutes using JavaScript's Date.getTimezoneOffset convention: positive values are behind UTC. For example, 480 is US Pacific Standard Time (UTC-08:00). |
| `next_cursor` | string | No | Opaque continuation token returned by a previous QUERY_DATA call. Pass it back unchanged; the original query and options are carried authoritatively. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Summarize Experiment or Dataset

**Slug:** `BRAINTRUST_SUMMARIZE_RESOURCE`

Return metadata and optional aggregate summaries for one Braintrust experiment or dataset.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_id` | string | Yes | Experiment or dataset UUID matching resource_type. |
| `resource_type` | string ("experiment" | "dataset") | Yes | Resource summary to calculate. |
| `include_aggregates` | boolean | No | For experiments, summarize scores and metrics; for datasets, summarize data. Set false to return metadata only. |
| `comparison_experiment_id` | string | No | Optional baseline experiment UUID. Valid only when resource_type is experiment and include_aggregates is true. When omitted, Braintrust may select the configured baseline or a recent experiment. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Dataset

**Slug:** `BRAINTRUST_UPDATE_DATASET`

Update the name, description, tags, or metadata of a Braintrust dataset. At least one non-null mutable field is required.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New dataset name. |
| `tags` | array | No | Complete replacement list of dataset tags. |
| `metadata` | object | No | Metadata fields to deep-merge into the dataset's existing metadata. |
| `dataset_id` | string | Yes | UUID of the dataset to update. |
| `description` | string | No | New dataset description. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Experiment

**Slug:** `BRAINTRUST_UPDATE_EXPERIMENT`

Update selected metadata and linkage fields on a Braintrust experiment. At least one non-null mutable field is required.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New experiment name. |
| `tags` | array | No | Complete replacement list of experiment tags. |
| `public` | boolean | No | Whether the experiment is publicly viewable. |
| `metadata` | object | No | User-controlled metadata fields to deep-merge into existing metadata. |
| `dataset_id` | string | No | UUID of the dataset to link to the experiment. |
| `description` | string | No | New experiment description. |
| `experiment_id` | string | Yes | UUID of the experiment to update. |
| `dataset_version` | string | No | Version of the linked dataset used by the experiment. |
| `base_experiment_id` | string | No | UUID of the default baseline experiment used for comparisons. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Project

**Slug:** `BRAINTRUST_UPDATE_PROJECT`

Update selected fields of a Braintrust project. At least one non-null mutable field is required: name, description, or settings.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New project name. |
| `settings` | object | No | Complete replacement project settings. Include every existing setting that must be retained. |
| `project_id` | string | Yes | UUID of the project to update. |
| `description` | string | No | New project description. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Prompt

**Slug:** `BRAINTRUST_UPDATE_PROMPT`

Update a Braintrust prompt's metadata or configuration without invoking it. At least one non-null mutable field is required.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | New prompt name. |
| `slug` | string | No | New unique prompt slug. |
| `tags` | array | No | Complete replacement list of prompt tags. |
| `prompt_id` | string | Yes | UUID of the prompt to update. |
| `description` | string | No | New prompt description. |
| `prompt_data` | object | No | Prompt block, model options, or parser fields to deep-merge. MCP attachments and tool_functions are unsupported and rejected. |
| `template_format` | string ("mustache" | "nunjucks" | "none") | No | Replacement template syntax, stored inside the provider's prompt_data object. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |