Braintrust TypeScript SDK

This page provides a complete, auto-generated reference for the Braintrust TypeScript SDK. For usage guidance on important APIs, see the API Reference. Also see the Braintrust TypeScript SDK on GitHub.

Installation

npm install braintrust

pnpm add braintrust

Starting with v2.0.0, if you’re using the Vercel AI SDK integration or other features that require schema validation, you must install zod as a peer dependency: npm install zod

Functions

addAzureBlobHeaders

addAzureBlobHeaders function

Record

string

agentAssertionScorer

Create an Eval scorer that will evaluate an agent based on assertions on the generated trace. The callback receives input, output, expected, metadata plus an assert helper object. It should return the assertions to evaluate the agent against. Important: Tool-call assertions require Braintrust tracing to be set up during the Eval so the scorer can read tool spans from the trace. The score emitted by this scorer is the fraction of assertions that passed. If there are no assertions, the score is 1. The score metadata includes every assertion’s name and pass/fail state, plus human-readable failure messages.

AgentAssertionScorerCallback

Object

string

The score name to emit. Defaults to "assertions".

BaseExperiment

Use this to specify that the dataset should actually be the data from a previous (base) experiment. If you do not specify a name, Braintrust will automatically figure out the best base experiment to use based on your git history (or fall back to timestamps).

Object

string

The name of the base experiment to use. If unspecified, Braintrust will automatically figure out the best base using your git history (or fall back to timestamps).

braintrustAISDKTelemetry

Creates a Braintrust telemetry integration for AI SDK v7’s registerTelemetry() API.

braintrustEveHook

Manual hook instrumentation for eve runtime stream events.

Object

EveDefineState

required

Record

braintrustEveInstrumentation

Braintrust instrumentation for Eve. Pass defineState when using Eve’s legacy authored instrumentation API. With Eve 0.34+, omit defineState to use the instrumentation-provider lifecycle. Eve before 0.62 also requires experimental.instrumentationProviders on the agent. The result is ready to export directly from the instrumentation module.

EveProviderInstrumentationOptions

braintrustFlueInstrumentation

Manual instrumentation for flue. This should be passed to flue’s instrument() API if not using auto-instrumentation: instrument(braintrustFlueInstrumentation())

braintrustFlueObserver

Observer for flue pre version 1.0.0. This observer should be passed to flue’s observe() API if not using auto-instrumentation.

unknown

BraintrustMiddleware

Creates a Braintrust middleware for AI SDK v2 that automatically traces generateText and streamText calls with comprehensive metadata and metrics.

MiddlewareConfig

Configuration options for the middleware

buildLocalSummary

buildLocalSummary function

EvaluatorDef

string

required

string

required

string

An optional experiment id to use as a base. If specified, the new experiment will be summarized and compared to this experiment. This takes precedence over baseExperimentName if specified.

string

An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment.

EvalClassifier[]

A set of functions that take an input, output, and expected value and return a Classification. Results are recorded under the classifications column. At least one of scores or classifiers must be provided.

EvalData

required

A function that returns a list of inputs, expected outputs, and metadata.

string

An optional description for the experiment.

ErrorScoreHandler

Optionally supply a custom function to specifically handle score values when tasks or scoring functions have errored. A default implementation is exported as defaultErrorScoreHandler which will log a 0 score to the root span for any scorer that was not run.

string

An optional name for the experiment.

boolean

Flushes spans before calling scoring functions

Object

Optional settings for collecting git metadata. By default, Braintrust collects the git metadata fields allowed by your organization’s git metadata settings. If those settings are absent, git metadata is not collected unless this option is set.

boolean

Whether the experiment should be public. Defaults to false.

number

The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency.

Record

Optional additional metadata for the experiment.

Parameters | RemoteEvalParameters | Promise

A set of parameters that will be passed to the evaluator. Can be:

A raw EvalParameters schema (Zod schemas)
A Parameters instance from loadParameters()
A Promise<Parameters> from loadParameters()

string

If specified, uses the given project ID instead of the evaluator’s name to identify the project.

null | Object

Optionally explicitly specify the git metadata for this experiment. This takes precedence over gitMetadataSettings if specified.

EvalScorer[]

A set of functions that take an input, output, and expected value and return a Score. At least one of scores or classifiers must be provided.

AbortSignal

An abort signal that can be used to stop the evaluation.On abort, trials that have not started are skipped and the task hooks’ signal is aborted. The evaluation then waits for in-flight tasks and scorers to settle before rejecting, so tasks that ignore the signal can delay the rejection.

BraintrustState

If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key).

boolean

Whether to summarize the scores of the experiment after it has run. Defaults to true.

string[]

Optional tags for the experiment.

EvalTask

required

A function that takes an input and returns an output.

number

The duration, in milliseconds, after which to time out the evaluation. A timeout of 0 times out immediately. Defaults to undefined, in which case there is no timeout.On timeout, trials that have not started are skipped and the task hooks’ signal is aborted. The evaluation then waits for in-flight tasks and scorers to settle before rejecting, so tasks that ignore the signal can make the evaluation take longer than timeout.

number

The number of times to run the evaluator per input. This is useful for evaluating applications that have non-deterministic behavior and gives you both a stronger aggregate measure and a sense of the variance in the results.

boolean

Whether to update an existing experiment with experiment_name if one exists. Defaults to false.

EvalResult[]

ScoreAccumulator

collectAnthropicSession

Collect a stream returned by anthropic.beta.sessions.events.stream() or anthropic.beta.sessions.threads.events.stream(). The stream method must be auto-instrumented or called through a client wrapped with wrapAnthropic(). Calling this function opts the stream into Braintrust span collection and returns the original stream unchanged.

The resolved Anthropic Sessions event stream.

completeAISDKBatchTrace

Capture already collected AI SDK batch results and finish the original spans. This does not poll, fetch results, or consume provider streams. The caller must collect the stream into records first, including results of failed batches. Pending batches and completed batches with missing results remain pending. Retrying with the same context and results updates the same rows. Without context, captures inputs and results together under the current parent. Original request IDs/models must match the context when one is supplied. Verify webhook signatures in application code; a webhook is not trace context.

CompleteAISDKBatchTraceArgs

completeOpenAIBatchTrace

Add result data to spans created by openaiFilesCreateTraced. This helper performs no OpenAI API requests. Pass the input file ID and the input, output, and error contents returned by openai.files.content, or pass JSONL strings/iterables directly. Response bodies are consumed. Call openaiBatchesRetrieveTraced first when exact OpenAI lifecycle timestamps are available.

CompleteOpenAIBatchTraceArgs

configureInstrumentation

Configure auto-instrumentation. This must be called before importing any AI SDKs to take effect.

InstrumentationConfig

InstrumentationIntegrationsConfig

Configuration for individual SDK integrations. Set to false to disable instrumentation for that SDK.

LangChainCaptureOptions

Capture settings for automatically injected LangChain/LangGraph handlers. All fields default to true. Disabled payloads are omitted before copying. Spans, timing, errors, and metadata remain available. Configure before initializing the SDK or loading braintrust/hook.mjs. Use provider instrumentation to capture model payloads and usage when disabling their capture here.

unknown

Customizers for all native SDK and Braintrust OpenTelemetry spans, in order. Native hooks receive span records; OTel hooks receive plain snapshots with attributes, events, links, resource, instrumentationScope and spanContext. Configure before initializing the SDK or enabling instrumentation.

number

Target attachment payload size in bytes for each segmentable media stream. Defaults to 4 MiB. Must be a positive safe integer. Instrumentations flush at valid media boundaries and on recording completion. Counts binary bytes after decoding and format conversion, excluding metadata. Audio recordings count raw PCM before compression, so compressed uploads are smaller than this size. Whole-file responses remain intact and may exceed this threshold. This is not a total memory limit and does not enable attachment capture. Configure before initializing the SDK or enabling instrumentation.

constructLogs3OverflowRequest

constructLogs3OverflowRequest function

string

createFinalValuePassThroughStream

Create a stream that passes through the final value of the stream. This is used to implement BraintrustStream.finalValue().

Object

A function to call with the final value of the stream.

Object

currentExperiment

Returns the currently-active experiment (set by init). Returns undefined if no current experiment has been set.

OptionalStateArg

currentLogger

Returns the currently-active logger (set by initLogger). Returns undefined if no current logger has been set.

unknown

currentSpan

Return the currently-active span for logging (set by one of the traced methods). If there is no active span, returns a no-op span object, which supports the same interface as spans but does no logging. See Span for full details.

OptionalStateArg

DatasetPipeline

Creates a runnable dataset pipeline. Dataset pipelines can be used to take trace data stored in Braintrust, filter and transform it, and directly feed it back into a Braintrust dataset. You can run a dataset pipeline with the bt CLI using bt datasets pipeline run some-file-path.ts --limit 100. The limit option controls how many spans/traces (depending on the definition.source.scope option) are discovered for the pipeline.

The API for this function is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.

DatasetPipelineDefinition

deepCopyEvent

Creates a deep copy of the given event. Replaces references to user objects with placeholder strings to ensure serializability, except for Attachment and ExternalAttachment objects, which are preserved and not deep-copied.

defaultErrorScoreHandler

defaultErrorScoreHandler function

Object

EvalCase

required

Span

required

string[]

required

defineWorkflowEval

Defines a workflow evaluation backed by a user-provided store.

The API for this function is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.

string

WorkflowEvaluator

deserializePlainStringAsJSON

deserializePlainStringAsJSON function

string

devNullWritableStream

devNullWritableStream function

Eval

Eval function

string

Evaluator

string

An optional experiment id to use as a base. If specified, the new experiment will be summarized and compared to this experiment. This takes precedence over baseExperimentName if specified.

string

An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment.

EvalClassifier[]

EvalData

required

A function that returns a list of inputs, expected outputs, and metadata.

string

An optional description for the experiment.

ErrorScoreHandler

string

An optional name for the experiment.

boolean

Flushes spans before calling scoring functions

Object

boolean

Whether the experiment should be public. Defaults to false.

number

The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency.

Record

Optional additional metadata for the experiment.

Parameters | RemoteEvalParameters | Promise

A set of parameters that will be passed to the evaluator. Can be:

A raw EvalParameters schema (Zod schemas)
A Parameters instance from loadParameters()
A Promise<Parameters> from loadParameters()

string

If specified, uses the given project ID instead of the evaluator’s name to identify the project.

null | Object

Optionally explicitly specify the git metadata for this experiment. This takes precedence over gitMetadataSettings if specified.

EvalScorer[]

A set of functions that take an input, output, and expected value and return a Score. At least one of scores or classifiers must be provided.

AbortSignal

BraintrustState

If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key).

boolean

Whether to summarize the scores of the experiment after it has run. Defaults to true.

string[]

Optional tags for the experiment.

EvalTask

required

A function that takes an input and returns an output.

number

boolean

Whether to update an existing experiment with experiment_name if one exists. Defaults to false.

string | ReporterDef | EvalOptions

extractTraceContextFromHeaders

Extract an opaque W3C trace-context from inbound request headers. This is the receive-side counterpart of Span.inject / injectTraceContext. The return value is an opaque propagation context that can be passed as parent to startSpan:

const ctx = extractTraceContextFromHeaders(request.headers);
traced((span) =&gt; { ... }, { name: "handler", parent: ctx });

Only the W3C Trace Context headers are interpreted (traceparent, baggage, tracestate); header lookups are case-insensitive. If no valid traceparent is present, returns undefined (the caller starts a fresh root span). The Braintrust container the trace is routed under is resolved when the span is created: from the braintrust.parent baggage entry, or else the currently-active logger/experiment. Callers should treat the return value as opaque.

undefined | null | TraceContextHeaders

Inbound request headers (e.g. an HTTP framework’s headers).

failOpenAIAgentsTrace

End a manual OpenAI Agents API trace after submission or observation fails. This helper performs no OpenAI API requests. It returns a terminal token so repeated delivery can remain idempotent.

OpenAIAgentsTraceToken

unknown

flush

Flush any pending rows to the server.

OptionalStateArg

getContextManager

getContextManager function

getIdGenerator

Factory function that creates a new ID generator instance each time. This eliminates global state and makes tests parallelizable. Each caller gets their own generator instance. Honors an explicitly-installed globalThis.BRAINTRUST_ID_GENERATOR (e.g. set by @braintrust/otel’s setupOtelCompat()). Otherwise it defaults to OpenTelemetry-compatible hex IDs, falling back to legacy UUID IDs when BRAINTRUST_LEGACY_IDS is set.

getPromptVersions

Get the versions for a prompt.

string

The ID of the project to query

string

The ID of the prompt to get versions for

getSpanParentObject

Mainly for internal use. Return the parent object for starting a span in a global context. Applies precedence: current span > propagated parent > experiment > logger. parent may be an exported slug string or an opaque W3C trace-context (from extractTraceContextFromHeaders).

unknown

string | PropagationContext

getTemplateRenderer

Gets an active template renderer by name. Returns undefined if the renderer is not active.

string

Name of the renderer to retrieve

init

Readonly

Options for configuring init().

string

The API key to use. If the parameter is not specified, will try to use the BRAINTRUST_API_KEY environment variable. In Node.js, if that is unset, will try the nearest .env.braintrust file in the current working directory or parent directories.

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

Controls internal Braintrust SDK troubleshooting output.Use "error", "warn", "info", or "debug" to control how much internal SDK troubleshooting output is emitted. Use false to explicitly disable this output.When omitted, the SDK remains silent unless BRAINTRUST_DEBUG_LOG_LEVEL is set to "error", "warn", "info", or "debug". This option only affects local console output; it does not change what data is logged to Braintrust.

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

string

AnyDataset | DatasetRef

string

GitMetadataSettingsType

boolean

Record

ParametersRef | RemoteEvalParameters

string

RepoInfoType

boolean

BraintrustState

string[]

boolean

initDataset

Initialize a dataset by name or ID. When initializing by name, the dataset and its project will be created if they do not exist.

Readonly

Options for configuring initDataset().

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

string

Record

string

BraintrustState

string

initExperiment

Alias for init(options).

Readonly

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

string

AnyDataset | DatasetRef

string

GitMetadataSettingsType

boolean

Record

ParametersRef | RemoteEvalParameters

string

RepoInfoType

boolean

BraintrustState

string[]

boolean

initFunction

Creates a function that can be used as a task or scorer in the Braintrust evaluation framework. The returned function wraps a Braintrust function and can be passed directly to Eval(). When used as a task:

const myFunction = initFunction({projectName: "myproject", slug: "myfunction"});
await Eval("test", {
  task: myFunction,
  data: testData,
  scores: [...]
});

When used as a scorer:

const myScorer = initFunction({projectName: "myproject", slug: "myscorer"});
await Eval("test", {
  task: someTask,
  data: testData,
  scores: [myScorer]
});

Object

Options for the function.

string

required

The project name containing the function.

string

required

The slug of the function to invoke.

BraintrustState

Optional Braintrust state to use.

string

Optional version of the function to use. Defaults to latest.

initLogger

Create a new logger in a specified project. If the project does not exist, it will be created.

Readonly

Additional options for configuring init().

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

SpanOriginEnvironment

OrgProjectMetadata

string

boolean

BraintrustState

initNodeTestSuite

Creates a new Node.js test suite with Braintrust experiment tracking.

NodeTestSuiteConfig

injectTraceContext

Inject W3C trace-context headers for the current (or given) span into a carrier. This is the free-function form of Span.inject, and the send-side counterpart of extractTraceContextFromHeaders. If no span is provided, the currently-active span is used. Propagation is best-effort and never throws.

undefined

Optional carrier (e.g. outbound HTTP headers) to mutate. Supports plain objects, Web Headers, Node-style setHeader carriers, framework header carriers, and mutable HeadersInit tuple arrays.

unknown

Span

Optional span to inject. Defaults to the current span.

invoke

Invoke a Braintrust function, returning a BraintrustStream or the value as a plain Javascript object.

unknown

The arguments for the function (see InvokeFunctionArgs for more details).

The type of the global function to invoke. If unspecified, defaults to ‘scorer’ for backward compatibility.

string

The ID of the function to invoke.

string

The name of the global function to invoke.

Input

required

The input to the function. This will be logged as the input field in the span.

Additional OpenAI-style messages to add to the prompt (only works for llm functions).

Record

Additional metadata to add to the span. This will be logged as the metadata field in the span. It will also be available as the {{metadata}} field in the prompt. For code functions, it is passed through the hooks (the handler’s second argument in TypeScript, hooks.metadata in Python), not as the handler’s metadata argument, which is read from input. To fill the handler’s metadata argument, nest it in input, e.g. invoke({ ..., input: { input: ..., metadata: { ... } } }).

null | "text" | "auto" | "parallel" | "json"

The mode of the function. If “auto”, will return a string if the function returns a string, and a JSON object otherwise. If “parallel”, will return an array of JSON objects with one object per tool call.

Record

Per-call deep-merge into the resolved function data server-side. Useful for facet, code, global, and remote_eval functions (for example, overriding a facet’s model or a global function’s config). Has no effect on prompt functions, whose parameters live on a separate field that the override path does not touch.

string | Exportable

The parent of the function. This can be an existing span, logger, or experiment, or the output of .export() if you are distributed tracing. If unspecified, will use the same semantics as traced() to determine the parent and no-op if not in a tracing context.

string

The ID of the project to use for execution context (API keys, project defaults, etc.). This is not the project the function belongs to, but the project context for the invocation.

string

The name of the project containing the function to invoke.

string

The ID of the function in the prompt session to invoke.

string

The ID of the prompt session to invoke the function from.

unknown

A Zod schema to validate the output of the function and return a typed value. This is only used if stream is false.

string

The slug of the function to invoke.

BraintrustState

(Advanced) This parameter allows you to pass in a custom login state. This is useful for multi-tenant environments where you are running functions from different Braintrust organizations.

Stream

Whether to stream the function’s output. If true, the function will return a BraintrustStream, otherwise it will return the output of the function as a JSON object.

boolean

Whether to use strict mode for the function. If true, the function will throw an error if the variable names in the prompt do not match the input keys.

string[]

Tags to add to the span. This will be logged as the tags field in the span.

string

The version of the function to invoke.

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

isTemplateFormat

isTemplateFormat function

unknown

loadParameters

Load parameters from the specified project.

LoadParametersByProjectNameOptions

Options for configuring loadParameters().

loadPrompt

Load a prompt from the specified project.

LoadPromptOptions

Options for configuring loadPrompt().

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

DefaultPromptArgs

string

boolean

string

BraintrustState

string

log

Log a single event to the current experiment. The event will be batched and uploaded behind the scenes.

ExperimentLogFullArgs

The event to log. See Experiment.log for full details.

unknown

required

string

required

logError

logError function

Span

string

required

Row ID of the span.

"span"

required

string

required

Root span ID of the span.

string

required

Span ID of the span.

string[]

required

Parent span IDs of the span.

unknown

Log into Braintrust. This will prompt you for your API token, which you can find at https://www.braintrust.dev/app/token. This method is called automatically by init().

unknown

Options for configuring login().

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

Login again, even if you have already logged in (by default, this function will exit quickly if you have already logged in)

loginToState

loginToState function

LoginOptions

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

newId

newId function

openaiBatchesRetrieveTraced

Wrap openai.batches.retrieve to update an OpenAI Batch trace with the server-recorded lifecycle timestamps and close its spans at a terminal status. Pass the openai.batches resource, then call the returned function with the same arguments as openai.batches.retrieve. The Batch must use an input file previously uploaded through openaiFilesCreateTraced in this process.

OpenAIBatchesResource

openaiFilesCreateTraced

Wrap openai.files.create to trace an OpenAI Batch input file upload. Pass the openai.files resource, then call the returned function with the same arguments as openai.files.create. Files whose purpose is not batch are passed through without tracing. Blob and Response uploads are copied for tracing; async-iterable uploads (including Node file streams) are teed so the exact bytes still flow to OpenAI while Braintrust reads a separate branch. The returned input file ID identifies the trace. Each request span is identified by that file ID and its JSONL custom_id, so use every traced input file for only one OpenAI Batch.

OpenAIFilesResource

parseCachedHeader

parseCachedHeader function

undefined | null | string

parseTemplateFormat

parseTemplateFormat function

unknown

TemplateFormat

permalink

Format a permalink to the Braintrust application for viewing the span represented by the provided slug. Links can be generated at any time, but they will only become viewable after the span and its root have been flushed to the server and ingested. If you have a Span object, use Span.link instead.

string

The identifier generated from Span.export.

Object

Optional arguments.

string

The app URL to use. If not provided, the app URL will be inferred from the state.

string

The org name to use. If not provided, the org name will be inferred from the state.

BraintrustState

The login state to use. If not provided, the global state will be used.

pickLogs3OverflowObjectIds

pickLogs3OverflowObjectIds function

Record

promptDefinitionToPromptData

promptDefinitionToPromptData function

unknown

string[]

string

required

objectOutputType | objectOutputType | objectOutputType | objectOutputType | objectOutputType

"none" | "mustache" | "nunjucks"

Object[]

registerOtelFlush

Register a callback to flush OTEL spans. This is called by @braintrust/otel when it initializes a BraintrustSpanProcessor/Exporter. When ensureSpansFlushed is called (e.g., before a BTQL query in scorers), this callback will be invoked to ensure OTEL spans are flushed to the server. Also disables the span cache, since OTEL spans aren’t in the local cache and we need BTQL to see the complete span tree (both native + OTEL spans).

Object

registerTemplatePlugin

Register a template plugin and optionally activate it If options is provided it will be used to create the active renderer. If options is omitted but the plugin defines defaultOptions, the registry will activate the renderer using those defaults.

TemplateRendererPlugin

Object

required

Factory function that creates a renderer instance.

unknown

Default configuration options for this plugin.

string

required

Unique identifier for this plugin. Must match the format string used in templateFormat option.

renderMessage

renderMessage function

Object

renderPromptParams

renderPromptParams function

Record

Object

boolean

TemplateFormat

renderTemplateContent

renderTemplateContent function

string

Record

Object

boolean

TemplateFormat

Reporter

Reporter function

string

ReporterBody

reportFailures

reportFailures function

EvaluatorDef

string

required

string

required

string

An optional experiment id to use as a base. If specified, the new experiment will be summarized and compared to this experiment. This takes precedence over baseExperimentName if specified.

string

An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment.

EvalClassifier[]

EvalData

required

A function that returns a list of inputs, expected outputs, and metadata.

string

An optional description for the experiment.

ErrorScoreHandler

string

An optional name for the experiment.

boolean

Flushes spans before calling scoring functions

Object

boolean

Whether the experiment should be public. Defaults to false.

number

The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency.

Record

Optional additional metadata for the experiment.

Parameters | RemoteEvalParameters | Promise

A set of parameters that will be passed to the evaluator. Can be:

A raw EvalParameters schema (Zod schemas)
A Parameters instance from loadParameters()
A Promise<Parameters> from loadParameters()

string

If specified, uses the given project ID instead of the evaluator’s name to identify the project.

null | Object

Optionally explicitly specify the git metadata for this experiment. This takes precedence over gitMetadataSettings if specified.

EvalScorer[]

A set of functions that take an input, output, and expected value and return a Score. At least one of scores or classifiers must be provided.

AbortSignal

BraintrustState

If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key).

boolean

Whether to summarize the scores of the experiment after it has run. Defaults to true.

string[]

Optional tags for the experiment.

EvalTask

required

A function that takes an input and returns an output.

number

boolean

Whether to update an existing experiment with experiment_name if one exists. Defaults to false.

EvalResult[]

ReporterOpts

runEvaluator

runEvaluator function

null | Experiment

EvaluatorDef

string

required

string

required

string

An optional experiment id to use as a base. If specified, the new experiment will be summarized and compared to this experiment. This takes precedence over baseExperimentName if specified.

string

An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment.

EvalClassifier[]

EvalData

required

A function that returns a list of inputs, expected outputs, and metadata.

string

An optional description for the experiment.

ErrorScoreHandler

string

An optional name for the experiment.

boolean

Flushes spans before calling scoring functions

Object

boolean

Whether the experiment should be public. Defaults to false.

number

The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency.

Record

Optional additional metadata for the experiment.

Parameters | RemoteEvalParameters | Promise

A set of parameters that will be passed to the evaluator. Can be:

A raw EvalParameters schema (Zod schemas)
A Parameters instance from loadParameters()
A Promise<Parameters> from loadParameters()

string

If specified, uses the given project ID instead of the evaluator’s name to identify the project.

null | Object

Optionally explicitly specify the git metadata for this experiment. This takes precedence over gitMetadataSettings if specified.

EvalScorer[]

A set of functions that take an input, output, and expected value and return a Score. At least one of scores or classifiers must be provided.

AbortSignal

BraintrustState

If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key).

boolean

Whether to summarize the scores of the experiment after it has run. Defaults to true.

string[]

Optional tags for the experiment.

EvalTask

required

A function that takes an input and returns an output.

number

boolean

Whether to update an existing experiment with experiment_name if one exists. Defaults to false.

ProgressReporter

Filter[]

undefined | Object

InferParameters

boolean

setFetch

Set the fetch implementation to use for requests. You can specify it here, or when you call login.

Object

The fetch implementation to use.

setMaskingFunction

Set a global masking function that will be applied to all logged data before sending to Braintrust. The masking function will be applied after records are merged but before they are sent to the backend. Internally, masking is a state-local export customizer that runs after any span customizers and also covers non-span records such as dataset rows and feedback.

null | Object

A function that takes a JSON-serializable object and returns a masked version. Set to null to disable masking.

spanComponentsToObjectId

spanComponentsToObjectId function

Object

SpanComponentsV3

required

BraintrustState

startAISDKBatchTrace

Capture inputs after the caller has successfully submitted an AI SDK text batch. This does not submit the batch or call any provider API. Persist the returned opaque context alongside the batch reference and original requests. Pass them to completeAISDKBatchTrace after collecting the results, including in another process. Flush the logger before handing off the work. The context contains routing and an input-identity digest, not prompts or keys. Treat it as trusted application state. Returns undefined if capture is disabled or the supplied data is unsupported.

StartAISDKBatchTraceArgs

startOpenAIAgentsTrace

Start a manual trace for one asynchronous OpenAI Agents API turn. This helper performs no OpenAI API requests. Pass it the same input, agent, and agent_id values used to create or continue the turn. metadata is copied to the Braintrust span and can also contain an application correlation ID when the same parameters are sent to OpenAI. The returned token can be persisted immediately before submission and passed with later events to updateOpenAIAgentsTrace. The trace closes when a root turn reaches a terminal state.

any

startSpan

Lower-level alternative to traced. This allows you to start a span yourself, and can be useful in situations where you cannot use callbacks. However, spans started with startSpan will not be marked as the “current span”, so currentSpan() and traced() will be no-ops. If you want to mark a span as current, use traced instead. See traced for full details.

unknown

StartSpanEventArgs

string

string | PropagationContext

The parent to start this span under. May be an exported span slug string (from span.export()) or an opaque W3C trace-context (from extractTraceContextFromHeaders).

ParentSpanIds | MultiParentSpanIds

StartSpanEventArgs

Record

string

number

SpanType

summarize

Summarize the current experiment, including the scores (compared to the closest reference experiment) and metadata.

Object

Options for summarizing the experiment.

string

The experiment to compare against. If None, the most recent experiment on the origin’s main branch will be used.

boolean

Whether to summarize the scores. If False, only the metadata will be returned.

traceable

A synonym for wrapTraced. If you’re porting from systems that use traceable, you can use this to make your codebase more consistent.

unknown

StartSpanEventArgs

string

string | PropagationContext

The parent to start this span under. May be an exported span slug string (from span.export()) or an opaque W3C trace-context (from extractTraceContextFromHeaders).

ParentSpanIds | MultiParentSpanIds

StartSpanEventArgs

Record

string

number

SpanType

boolean

traced

Toplevel function for starting a span. It checks the following (in precedence order):

Currently-active span
Currently-active experiment
Currently-active logger

and creates a span under the first one that is active. Alternatively, if parent is specified, it creates a span under the specified parent row. If none of these are active, it returns a no-op span object. See Span.traced for full details.

Object

unknown

StartSpanEventArgs

string

string | PropagationContext

The parent to start this span under. May be an exported span slug string (from span.export()) or an opaque W3C trace-context (from extractTraceContextFromHeaders).

ParentSpanIds | MultiParentSpanIds

StartSpanEventArgs

Record

string

number

SpanType

boolean

updateOpenAIAgentsTrace

Apply an OpenAI Agents event to a trace and return its next resumable token. This helper performs no OpenAI API requests. It is intended for stream, webhook, and worker processes that observe events from a turn. Events should be applied in order, passing the returned token to the next call.

OpenAIAgentsTraceToken

any

updateSpan

Update a span using the output of span.export(). It is important that you only resume updating to a span once the original span has been fully written and flushed, since otherwise updates to the span may conflict with the original span.

unknown

string

required

uploadLogs3OverflowPayload

Upload a logs3 overflow payload to the signed URL. This is a standalone function that can be used by both SDK and app code.

Object

The overflow upload metadata from the API

Record

string

required

"POST" | "PUT"

required

string

required

string

The JSON payload string to upload

Object

Optional custom fetch function (defaults to global fetch)

utf8ByteLength

utf8ByteLength function

string

withCurrent

Runs the provided callback with the span as the current span.

Span

string

required

Row ID of the span.

"span"

required

string

required

Root span ID of the span.

string

required

Span ID of the span.

string[]

required

Parent span IDs of the span.

Object

BraintrustState

withDataset

withDataset function

string

Object

Readonly

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

string

Record

string

BraintrustState

string

withExperiment

withExperiment function

string

Object

Readonly

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

string

AnyDataset | DatasetRef

string

Object

boolean

Record

ParametersRef | RemoteEvalParameters

string

null | Object

boolean

BraintrustState

string[]

boolean

withLogger

withLogger function

Object

Readonly

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

SpanOriginEnvironment

OrgProjectMetadata

string

boolean

BraintrustState

boolean

withParent

withParent function

string | PropagationContext

Object

BraintrustState

wrapAgentClass

wrapAgentClass function

any

WrapAISDKOptions

wrapAISDK

Wraps Vercel AI SDK methods with Braintrust tracing. For code-mode without a loader hook, wrap the code-mode namespace and call wrapAISDK(codeMode).experimental_runCodeMode(...). Factory-created tools call runCodeMode internally and require auto-instrumentation.

WrapAISDKOptions

wrapAISDKModel

Wrap an ai-sdk model (created with .chat(), .completion(), etc.) to add tracing. If Braintrust is not configured, this is a no-op

wrapAnthropic

Wrap an Anthropic object (created with new Anthropic(...)) so calls emit tracing-channel events that Braintrust plugins can consume. Also supports AnthropicBedrock and AnthropicVertex clients through their shared Anthropic message resources. Currently, this only supports the v4 API. Sessions streams are eligible for collection only after being passed to collectAnthropicSession(); wrapping and consuming a Sessions stream alone does not emit spans.

wrapBedrockRuntime

Wrap an AWS Bedrock Runtime client with Braintrust tracing.

wrapClaudeAgentSDK

Wraps the Claude Agent SDK with Braintrust tracing. Query calls only publish invocation hooks; the Claude Agent SDK plugin owns all span lifecycle work, including root/task spans, LLM spans, tool spans, and sub-agent spans.

The Claude Agent SDK module

wrapCloudflareAgent

Adds Braintrust tracing to a Cloudflare Agents base Agent class. The returned value is the same class, patched in place so existing Durable Object exports and inheritance continue to work unchanged.

wrapCloudflareAIChat

Wraps the @cloudflare/ai-chat module with Braintrust tracing. Pass the module namespace (import * as aiChat from "@cloudflare/ai-chat") and subclass the wrapped AIChatAgent export. The wrapper emits the same diagnostic-channel events as automatic instrumentation.

wrapCloudflareThink

Adds Braintrust tracing to an @cloudflare/think module when build-time auto-instrumentation is unavailable.

wrapCohere

Wrap a Cohere client so method calls emit diagnostics-channel events that Braintrust plugins can consume.

wrapConsole

Instrument future console.log/trace/debug/info/warn/error calls in place. log maps to info; other methods retain their severity. Existing console output is preserved. Repeated calls update the destination without duplicating logs. When no logger is supplied, each call uses the current project logger. Before a logger is initialized, calls produce their normal console output only. Returns an idempotent cleanup function that stops forwarding for this wrap. Cleanup does not disable a later wrap or flush already captured logs.

LogConsole

WrapConsoleOptions

wrapCopilotClient

Wrap a CopilotClient instance (created with new CopilotClient(...)) with Braintrust tracing. The wrapper intercepts createSession and resumeSession so that the same plugin logic used by auto-instrumentation applies — session spans, turn spans, LLM spans with token metrics, and tool spans are all produced.

wrapCursorSDK

Wraps the Cursor TypeScript SDK with Braintrust tracing. The wrapper emits invocation hooks; the Cursor SDK plugin owns span lifecycle.

wrapElevenLabs

Trace an ElevenLabs client (SDK 2.67+) with Braintrust. Captures speech generation, timestamped/streaming audio, and request/response transcription. Audio is attached as the application consumes it. Webhook transcription and Speech Engine sessions are not instrumented.

wrapFastMCP

Trace FastMCP 3.35+ and 4.x servers with Braintrust. Wrap the module before starting servers. This installs an idempotent session hook for all servers created by that module, including stateless HTTP requests. Content capture is controlled by integrations.fastmcp.captureContent.

wrapGenkit

Wrap a Genkit instance or module so Genkit calls emit diagnostics-channel events that Braintrust plugins can consume. This supports both:

const ai = wrapGenkit(genkit({ ... }))
wrapping the module namespace and then calling its genkit factory

wrapGoogleADK

Wrap a Google ADK module (imported with import * as adk from '@google/adk') to add tracing. If Braintrust is not configured, nothing will be traced. This wraps:

Runner.runAsync / InMemoryRunner.runAsync — top-level agent execution
BaseAgent.runAsync (and all subclasses) — individual agent invocations
BaseTool.runAsync / FunctionTool.runAsync — tool execution

LLM calls are already traced via the existing @google/genai instrumentation, since ADK uses GenAI internally.

The Google ADK module

wrapGoogleGenAI

Wrap a Google GenAI module (imported with import * as googleGenAI from '@google/genai') to add tracing. If Braintrust is not configured, nothing will be traced.

The Google GenAI module

wrapGoogleGenerativeAI

Trace @google/generative-ai model and chat calls through Braintrust.

wrapGroq

Wrap a Groq client (created with new Groq(...)) with Braintrust tracing.

wrapHuggingFace

Wrap a HuggingFace Inference SDK module or client with Braintrust tracing. Supports the LLM and embeddings APIs we intentionally instrument:

chatCompletion
chatCompletionStream
textGeneration
textGenerationStream
featureExtraction

HuggingFaceModule

wrapHuggingFaceTransformers

wrapHuggingFaceTransformers function

HuggingFaceTransformersModule

wrapLangGraphSDK

Trace LangGraph Platform runs that the caller waits for or streams.

wrapLangSmithClient

wrapLangSmithClient function

wrapLangSmithRunTrees

wrapLangSmithRunTrees function

wrapLangSmithTraceable

wrapLangSmithTraceable function

wrapLiveKit

Trace a LiveKit Agents (1.9.x) module with Braintrust. Captures cascade voice sessions: user and agent turns, speech, STT, LLM responses, TTS and function tools. Call audio is recorded as attachments per direction: set BRAINTRUST_CAPTURE_USER_AUDIO_ATTACHMENTS for caller audio and BRAINTRUST_CAPTURE_AGENT_AUDIO_ATTACHMENTS for agent audio. Recordings are Ogg Opus when @braintrust/audio is installed, and raw PCM otherwise. Wrap the module before constructing sessions; only sessions created through the wrapped module are traced.

wrapMastraAgent

wrapMastraAgent function

Object

string

wrapMCPHandler

Wrap the createMcpHandler factory from mcp-handler to trace incoming MCP requests with the same conventions as wrapMCPServer. Configure this integration with integrations.mcpHandler.

wrapMCPServer

Trace incoming MCP requests through response sending. Accepts an McpServer or low-level Server from @modelcontextprotocol/sdk or @modelcontextprotocol/server, and returns the same instance.

wrapMistral

Wrap a Mistral client (created with new Mistral(...)) with Braintrust tracing.

wrapOllama

Wrap an Ollama client so generation and embedding calls emit Braintrust diagnostics-channel events.

wrapOpenAI

Wrap an OpenAI object (created with new OpenAI(...)) to add tracing. If Braintrust is not configured, nothing will be traced. If this is not an OpenAI object, this function is a no-op. Currently, this supports the v4, v5, v6, and v7 API.

wrapOpenAICodexSDK

Wraps the OpenAI Codex TypeScript SDK with Braintrust tracing. The wrapper emits diagnostics-channel events; the OpenAI Codex plugin owns span lifecycle.

wrapOpenAIv4

wrapOpenAIv4 function

wrapOpenRouter

Wrap an OpenRouter client (created with new OpenRouter(...)) so calls emit diagnostics-channel events that Braintrust plugins can consume.

wrapOpenRouterAgent

Wrap an @openrouter/agent OpenRouter client so callModel() emits diagnostics-channel events consumed by the OpenRouter Agent plugin.

wrapPiCodingAgentSDK

Wraps the Pi Coding Agent SDK with Braintrust tracing. The wrapper emits instrumentation hook calls; the Pi Coding Agent plugin owns span lifecycle.

wrapStrandsAgentSDK

Wraps the Strands Agent SDK with Braintrust tracing. The wrapper invokes typed instrumentation channels; the Strands plugin owns span lifecycle.

wrapTraced

Wrap a function with traced, using the arguments as input and return value as output. Any functions wrapped this way will automatically be traced, similar to the @traced decorator in Python. If you want to correctly propagate the function’s name and define it in one go, then you can do so like this:

const myFunc = wrapTraced(async function myFunc(input) {
 const result = await client.chat.completions.create({
   model: "gpt-3.5-turbo",
   messages: [{ role: "user", content: input }],
 });
 return result.choices[0].message.content ?? "unknown";
},
// Optional: if you're using a framework like NextJS that minifies your code, specify the function name and it will be used for the span name
{ name: "myFunc" },
);

Now, any calls to myFunc will be traced, and the input and output will be logged automatically. If tracing is inactive, i.e. there is no active logger or experiment, it’s just a no-op.

The function to wrap.

unknown

Span-level arguments (e.g. a custom name or type) to pass to traced.

StartSpanEventArgs

string

string | PropagationContext

The parent to start this span under. May be an exported span slug string (from span.export()) or an opaque W3C trace-context (from extractTraceContextFromHeaders).

ParentSpanIds | MultiParentSpanIds

StartSpanEventArgs

Record

string

number

SpanType

boolean

wrapTypeSafe

Wrap a TypeSafe client so systemOne calls pass through Braintrust tracing.

wrapVitest

Wraps Vitest methods with Braintrust experiment tracking. This automatically creates datasets and experiments from your Vitest tests, tracking pass/fail rates and evaluation metrics. Experiments are automatically flushed after all tests complete.

VitestMethods

Object containing Vitest methods (test, describe, expect, etc.)

WrapperConfig

Optional configuration object

wrapVoyageAI

Wrap a Voyage AI client so method calls pass through the Braintrust instrumentation hooks.

wrapWorkersAI

Trace Clef and Clairic calls on a Workers AI binding. Other models and raw-response/streaming modes pass through unchanged.

Classes

Attachment

Represents an attachment to be uploaded and the associated metadata. Attachment objects can be inserted anywhere in an event, allowing you to log arbitrary file data. The SDK will asynchronously upload the file to object storage and replace the Attachment object with an AttachmentReference. Properties

Object

The object that replaces this Attachment at upload time.

Methods data(), debugInfo(), upload()

BaseAttachment

BaseAttachment class Properties

Object | Object

Methods data(), debugInfo(), upload()

BraintrustLangChainCallbackHandler

BraintrustLangChainCallbackHandler class Properties

string

Methods endSpan(), handleAgentAction(), handleAgentEnd(), handleChainEnd(), handleChainError(), handleChainStart(), handleChatModelStart(), handleLLMEnd(), handleLLMError(), handleLLMNewToken(), handleLLMStart(), handleRetrieverEnd(), handleRetrieverError(), handleRetrieverStart(), handleToolEnd(), handleToolError(), handleToolStart(), startSpan()

BraintrustObservabilityExporter

Translates Mastra TracingEvents into Braintrust spans. Construct one instance per Observability config (Mastra holds onto it for the process lifetime). Safe to register on multiple Mastra instances, but each instance maintains its own span map keyed by Mastra spanId. Properties

"braintrust"

Methods exportTracingEvent(), flush(), shutdown()

BraintrustState

BraintrustState class Properties

null | string

undefined | Experiment

undefined | Logger

IsoAsyncLocalStorage

DebugLogLevel

Object

string

boolean

null | string

ParametersCache

PromptCache

null | string

SpanCache

undefined | SpanOriginEnvironment

unknown

Methods [RESET_CONTEXT_MANAGER_STATE](), apiConn(), appConn(), bgLogger(), copyLoginInfo(), disable(), enforceQueueSizeLimit(), flushOtel(), getDebugLogLevel(), hasDebugLogLevelOverride(), httpLogger(), login(), loginReplaceApiConn(), proxyConn(), registerOtelFlush(), resetIdGenState(), resetLoginInfo(), serialize(), setDebugLogLevel(), setFetch(), setMaskingFunction(), setOverrideBgLogger(), toJSON(), toString(), deserialize()

BraintrustStream

A Braintrust stream. This is a wrapper around a ReadableStream of BraintrustStreamChunk, with some utility methods to make them easy to log and convert into various formats. Methods [asyncIterator](), copy(), finalValue(), toReadableStream(), parseRawEvent(), serializeRawEvent()

CachedSpanFetcher

Fetches spans for one root span, reusing complete results and results that are authoritative for a requested span type. Advanced filtered results are never cached because they do not represent every span of their type. Methods getSpans()

CodeFunction

CodeFunction class Properties

string

"error" | "ignore" | "replace"

Record

string

ZodSchema

Project

ZodSchema

string

string[]

Methods key()

CodePrompt

CodePrompt class Properties

string

string[]

string

"error" | "ignore" | "replace"

Record

string

Project

Object

string

string[]

Object | Object | GenericCodeFunction[]

Methods toFunctionDefinition()

ContextManager

ContextManager class Methods getCurrentSpan(), getParentSpanIds(), runInContext(), wrapSpanForStore()

Dataset

A dataset is a collection of records, such as model inputs and expected outputs, which represent data you can use to evaluate and fine-tune models. You can log production data to datasets, curate them with interesting examples, edit/delete records, and run evaluations against them. You should not create Dataset objects directly. Instead, use the braintrust.initDataset() method. Properties

unknown

Methods [asyncIterator](), clearCache(), close(), createSnapshot(), delete(), deleteSnapshot(), fetch(), fetchedData(), flush(), getInternalBtql(), getPinnedVersion(), getSnapshot(), getState(), insert(), listSnapshots(), restore(), restorePreview(), setPinnedVersion(), summarize(), toEvalData(), update(), updateSnapshot(), version(), isDataset()

EvalResultWithSummary

EvalResultWithSummary class Properties

EvalResult[]

ExperimentSummary

Methods toJSON(), toString()

Experiment

An experiment is a collection of logged events, such as model inputs and outputs, which represent a snapshot of your application at a particular point in time. An experiment is meant to capture more than just the model you use, and includes the data you use to test, pre- and post- processing code, comparison metrics (scores), and any other metadata you want to include. Experiments are associated with a project, and two experiments are meant to be easily comparable via their inputs. You can change the attributes of the experiments in a project (e.g. scoring functions) over time, simply by changing what you log. You should not create Experiment objects directly. Instead, use the braintrust.init() method. Properties

AnyDataset

"experiment"

unknown

Methods [asyncIterator](), clearCache(), close(), export(), fetch(), fetchBaseExperiment(), fetchedData(), flush(), getInternalBtql(), getPinnedVersion(), getState(), log(), logFeedback(), setPinnedVersion(), startSpan(), summarize(), traced(), updateSpan(), version()

ExternalAttachment

Represents an attachment that resides in an external object store and the associated metadata. ExternalAttachment objects can be inserted anywhere in an event, similar to Attachment objects, but they reference files that already exist in an external object store rather than requiring upload. The SDK will replace the ExternalAttachment object with an AttachmentReference during logging. Properties

Object

The object that replaces this ExternalAttachment at upload time.

Methods data(), debugInfo(), upload()

FailedHTTPResponse

FailedHTTPResponse class Properties

unknown

string

number

string

IDGenerator

Abstract base class for ID generators Methods getSpanId(), getTraceId(), shareRootSpanId()

JSONAttachment

Represents a JSON object that should be stored as an attachment. JSONAttachment is a convenience function that creates an Attachment from JSON data. It’s particularly useful for large JSON objects that would otherwise bloat the trace size. The JSON data is automatically serialized and stored as an attachment with content type “application/json”. Properties

Object

The object that replaces this Attachment at upload time.

Methods data(), debugInfo(), upload()

LazyValue

LazyValue class Properties

unknown

Methods get(), getSync()

LocalTrace

SDK implementation of Trace that uses local span cache and falls back to BTQL. Carries identifying information about the evaluation so scorers can perform richer logging or side effects. Methods getConfiguration(), getSpans(), getThread(), toJSON()

Logger

Logger class Properties

"logger"

unknown

Methods debug(), error(), export(), fatal(), flush(), fmt(), info(), log(), logFeedback(), startSpan(), trace(), traced(), updateSpan(), warn()

LoginInvalidOrgError

LoginInvalidOrgError class Properties

string

NoopSpan

A fake implementation of the Span API which does nothing. This can be used as the default span. Properties

string

Row ID of the span.

"span"

string

Root span ID of the span.

string

Span ID of the span.

string[]

Parent span IDs of the span.

Methods close(), end(), export(), flush(), getParentInfo(), inject(), link(), log(), logFeedback(), permalink(), setAttributes(), startSpan(), startSpanWithParents(), state(), toString(), traced()

ObjectFetcher

ObjectFetcher class Properties

unknown

Methods [asyncIterator](), clearCache(), fetch(), fetchedData(), getInternalBtql(), getPinnedVersion(), getState(), setPinnedVersion(), version()

OTELIDGenerator

ID generator that produces OpenTelemetry-compatible hex IDs. Span IDs are 8 random bytes (16 hex chars) and trace IDs are 16 random bytes (32 hex chars), matching the W3C Trace Context / OpenTelemetry shape. Trace ids are distinct from span ids (root_span_id is a separate trace id, not the root span’s id), so shareRootSpanId() returns false. Methods getSpanId(), getTraceId(), shareRootSpanId()

Project

Project class Properties

ClassifierBuilder

string

ParametersBuilder

string

PromptBuilder

ScorerBuilder

ToolBuilder

Methods addCodeFunction(), addParameters(), addPrompt(), publish()

ProjectNameIdMap

ProjectNameIdMap class Methods getId(), getName(), resolve()

Prompt

Prompt class Properties

unknown

Methods build(), buildWithAttachments(), fromPromptData(), isPrompt(), renderPrompt()

PromptBuilder

PromptBuilder class Methods create()

ReadonlyAttachment

A readonly alternative to Attachment, which can be used for fetching already-uploaded Attachments. Properties

Object | Object

Attachment metadata.

Methods asBase64Url(), data(), metadata(), status()

ReadonlyExperiment

A read-only view of an experiment, initialized by passing open: true to init(). Properties

unknown

Methods [asyncIterator](), asDataset(), clearCache(), fetch(), fetchedData(), getInternalBtql(), getPinnedVersion(), getState(), setPinnedVersion(), version()

ScorerBuilder

ScorerBuilder class Methods create()

SpanFetcher

Fetcher for spans by root_span_id, using the ObjectFetcher pattern. Handles pagination automatically via cursor-based iteration. Properties

unknown

Methods [asyncIterator](), clearCache(), fetch(), fetchedData(), getInternalBtql(), getPinnedVersion(), getState(), setPinnedVersion(), version()

SpanImpl

Primary implementation of the Span interface. See Span for full details on each method. We suggest using one of the various traced methods, instead of creating Spans directly. See Span.startSpan for full details. Properties

"span"

unknown

Row ID of the span.

unknown

Root span ID of the span.

unknown

Span ID of the span.

unknown

Parent span IDs of the span.

Methods close(), end(), export(), flush(), getParentInfo(), inject(), link(), log(), logFeedback(), permalink(), setAttributes(), setSpanParents(), startSpan(), startSpanWithParents(), state(), toString(), traced()

TestBackgroundLogger

TestBackgroundLogger class Methods drain(), flush(), flushBackpressureBytes(), log(), pendingFlushBytes(), setMaskingFunction()

ToolBuilder

ToolBuilder class Methods create()

UUIDGenerator

ID generator that uses UUID4 for both span and trace IDs Methods getSpanId(), getTraceId(), shareRootSpanId()

WorkflowBatchScorer

Defines a scorer that submits many cases/trials in each asynchronous provider batch, such as the OpenAI Batch API or Anthropic Message Batches.

The API for this class is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.

Properties

"braintrust.workflow.scorer"

string

unknown

WorkflowBatchTask

Defines a task that submits many cases/trials in each asynchronous provider batch, such as the OpenAI Batch API or Anthropic Message Batches.

The API for this class is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.

Properties

"braintrust.workflow.task"

WorkflowBatchProcessor

WorkflowEvalMemoryStore

Stores workflow evaluation state in memory. State is lost when the current JavaScript process exits.

The API for this class is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.

Methods addToSet(), getOrSet(), getSetSize(), read(), write()

WorkflowEvalRedisStore

Stores workflow evaluation state in Redis using an existing Redis client. Records are base64 encoded. Atomic progress sets use Redis Lua scripts. Clients from redis (node-redis), ioredis, and @upstash/redis can be passed directly.

The API for this class is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.

Methods addToSet(), getOrSet(), getSetSize(), read(), write()

WorkflowScorer

Defines a scorer that submits one asynchronous provider operation per case/trial.

The API for this class is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.

Properties

"braintrust.workflow.scorer"

string

unknown

WorkflowTask

Defines a task that submits one asynchronous provider operation per case/trial.

The API for this class is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.

Properties

"braintrust.workflow.task"

WorkflowSubmissionProcessor

Interfaces

AttachmentParams

AttachmentParams interface Properties

string

string | Blob | ArrayBuffer

string

BraintrustState

BackgroundLoggerOpts

BackgroundLoggerOpts interface Properties

boolean

Object

ContextParentSpanIds

ContextParentSpanIds interface Properties

string

string[]

DatasetSummary

Summary of a dataset’s scores and metadata. Properties

undefined | DataSummary

Summary of the dataset’s data.

string

Name of the dataset.

string

URL to the experiment’s page in the Braintrust app.

string

Name of the project that the dataset belongs to.

string

URL to the project’s page in the Braintrust app.

DataSummary

Summary of a dataset’s data. Properties

number

New or updated records added in this session.

number

Total records in the dataset.

EvalHooks

EvalHooks interface Properties

Expected

The expected output for the current evaluation.

Object

unknown

The metadata object for the current evaluation. You can mutate this object to add or remove metadata.

InferParameters

The current parameters being used for this specific task execution. Array parameters are converted to single values.

Object

Report progress that will show up in the playground.

AbortSignal

Aborted when the evaluation times out or its signal is aborted. Cancellation is cooperative: pass this to the APIs you call or check signal.aborted to stop work early.

Span

The task’s span.

undefined | string[]

The tags for the current evaluation.

number

The index of the current trial (0-based). This is useful when trialCount > 1.

Evaluator

Defines an evaluator. At least one of scores or classifiers must be provided. Properties

string

An optional experiment id to use as a base. If specified, the new experiment will be summarized and compared to this experiment. This takes precedence over baseExperimentName if specified.

string

An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment.

EvalClassifier[]

EvalData

A function that returns a list of inputs, expected outputs, and metadata.

string

An optional description for the experiment.

ErrorScoreHandler

string

An optional name for the experiment.

boolean

Flushes spans before calling scoring functions

Object

boolean

Whether the experiment should be public. Defaults to false.

number

The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency.

Record

Optional additional metadata for the experiment.

Parameters | RemoteEvalParameters | Promise

A set of parameters that will be passed to the evaluator. Can be:

A raw EvalParameters schema (Zod schemas)
A Parameters instance from loadParameters()
A Promise<Parameters> from loadParameters()

string

If specified, uses the given project ID instead of the evaluator’s name to identify the project.

null | Object

Optionally explicitly specify the git metadata for this experiment. This takes precedence over gitMetadataSettings if specified.

EvalScorer[]

A set of functions that take an input, output, and expected value and return a Score. At least one of scores or classifiers must be provided.

AbortSignal

BraintrustState

If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key).

boolean

Whether to summarize the scores of the experiment after it has run. Defaults to true.

string[]

Optional tags for the experiment.

EvalTask

A function that takes an input and returns an output.

number

boolean

Whether to update an existing experiment with experiment_name if one exists. Defaults to false.

ExperimentSummary

Summary of an experiment’s scores and metadata. Properties

string

The experiment scores are baselined against.

string

ID of the experiment. May be undefined if the eval was run locally.

string

Name of the experiment.

string

URL to the experiment’s page in the Braintrust app.

Record

string

Name of the project that the experiment belongs to.

string

URL to the project’s page in the Braintrust app.

Record

Summary of the experiment’s scores.

Exportable

Exportable interface

ExternalAttachmentParams

ExternalAttachmentParams interface Properties

string

BraintrustState

string

FunctionEvent

FunctionEvent interface Properties

string

Object[]

"error" | "ignore" | "replace"

Record

string

Object

string

string[]

GetThreadOptions

Options for getThread(). Properties

string

The preprocessor to use for extracting the thread. If not specified, uses the project default preprocessor, falling back to the global “thread” preprocessor.

InstrumentationConfig

InstrumentationConfig interface Properties

InstrumentationIntegrationsConfig

Configuration for individual SDK integrations. Set to false to disable instrumentation for that SDK.

LangChainCaptureOptions

unknown

number

InvokeFunctionArgs

Arguments for the invoke function. Properties

The type of the global function to invoke. If unspecified, defaults to ‘scorer’ for backward compatibility.

string

The ID of the function to invoke.

string

The name of the global function to invoke.

Input

The input to the function. This will be logged as the input field in the span.

Additional OpenAI-style messages to add to the prompt (only works for llm functions).

Record

null | "text" | "auto" | "parallel" | "json"

Record

string | Exportable

string

The ID of the project to use for execution context (API keys, project defaults, etc.). This is not the project the function belongs to, but the project context for the invocation.

string

The name of the project containing the function to invoke.

string

The ID of the function in the prompt session to invoke.

string

The ID of the prompt session to invoke the function from.

unknown

A Zod schema to validate the output of the function and return a typed value. This is only used if stream is false.

string

The slug of the function to invoke.

BraintrustState

(Advanced) This parameter allows you to pass in a custom login state. This is useful for multi-tenant environments where you are running functions from different Braintrust organizations.

Stream

Whether to stream the function’s output. If true, the function will return a BraintrustStream, otherwise it will return the output of the function as a JSON object.

boolean

Whether to use strict mode for the function. If true, the function will throw an error if the variable names in the prompt do not match the input keys.

string[]

Tags to add to the span. This will be logged as the tags field in the span.

string

The version of the function to invoke.

LoginOptions

Options for logging in to Braintrust. Properties

string

The URL of the Braintrust App. Defaults to https://www.braintrust.dev. You should not need to change this unless you are doing the “Full” deployment.

false | DebugLogLevel

boolean

If true, disables the local span cache used to optimize scorer access to trace data. When disabled, scorers will always fetch spans from the server. Defaults to false.

Object

A custom fetch implementation to use.

boolean

By default, the SDK installs an event handler that flushes pending writes on the beforeExit event. If true, this event handler will not be installed.

Object

Calls this function if there’s an error in the background flusher.

string

The name of a specific organization to connect to. Since API keys are scoped to organizations, this parameter is usually unnecessary unless you are logging in with a JWT.

LogOptions

LogOptions interface Properties

IsAsyncFlush

Record

LinkArgs

MastraObservabilityExporter

Subset of the ObservabilityExporter contract from @mastra/core. Properties

string

MetricSummary

Summary of a metric’s performance. Properties

number

Difference in metric between the current and reference experiment.

number

Number of improvements in the metric.

number

Average metric across all examples.

string

Name of the metric.

number

Number of regressions in the metric.

string

Unit label for the metric.

ObjectMetadata

ObjectMetadata interface Properties

Record

string

ParentExperimentIds

ParentExperimentIds interface Properties

string

ParentProjectLogIds

ParentProjectLogIds interface Properties

"g"

string

ParsedTraceparent

Parsed W3C traceparent fields. traceFlags is the raw 2-hex trace-flags byte (e.g. "01" sampled, "00" not sampled), kept raw so any future flag bits survive a parse -> format round trip without per-bit handling. Properties

string

PropagatedState

Inbound W3C trace-context state that Braintrust forwards but never interprets. Captured at the span created from inbound headers (via extractTraceContextFromHeaders) and inherited by every subspan, so that any inject() within the trace re-emits the upstream state unchanged, per the W3C Trace Context spec.

tracestate: the W3C tracestate header (opaque vendor state).
traceFlags: the raw 2-hex traceparent trace-flags byte. Stored raw so future flag bits are preserved without per-bit handling.
braintrustParent: the resolved braintrust.parent value, kept so id-based propagated parents can be re-injected synchronously before their lazy object id has been awaited.

Properties

string

ReporterBody

ReporterBody interface

ScoreSummary

Summary of a score’s performance. Properties

number

Difference in score between the current and reference experiment.

number

Number of improvements in the score.

string

Name of the score.

number

Number of regressions in the score.

number

Average score across all examples.

Span

A Span encapsulates logged data and metrics for a unit of work. This interface is shared by all span implementations. We suggest using one of the various traced methods, instead of creating Spans directly. See Span.traced for full details. Properties

string

Row ID of the span.

"span"

string

Root span ID of the span.

string

Span ID of the span.

string[]

Parent span IDs of the span.

SpanCustomizer

SpanCustomizer interface

SpanData

Span data returned by getSpans(). Properties

unknown

Record

unknown

Object

string

string[]

SpanDurationFilter

Inclusive span duration bounds, in seconds. Properties

number

Maximum value of metrics.end - metrics.start.

number

Minimum value of metrics.end - metrics.start.

SpanFilters

Filters supported by Trace.getSpans(). Different fields combine with AND. Empty name/spanType arrays match no spans. Empty metadata/duration objects add no constraints. Omit a field to leave it unfiltered. Properties

SpanDurationFilter

Bound how long the span took.

boolean

Match spans based on whether they recorded an error.

Record

Match metadata keys at any depth without type coercion. null matches a null or missing path.

string[]

Match spans whose span_attributes.name equals any of these.

string[]

Match spans whose span_attributes.type equals any of these.

TemplateRenderer

TemplateRenderer interface Properties

Object

TemplateRendererPlugin

A template renderer plugin that can be registered with Braintrust. Plugins provide support for different template engines (e.g., Nunjucks). They use a factory pattern where the plugin is registered once, then activated with specific configuration options when needed. Properties

Object

Factory function that creates a renderer instance.

unknown

Default configuration options for this plugin.

string

Unique identifier for this plugin. Must match the format string used in templateFormat option.

Trace

Interface for trace objects that can be used by scorers. Both the SDK’s LocalTrace class and the API wrapper’s WrapperTrace implement this.

WorkflowEvalStore

Minimal persistence used to reconnect provider webhooks with provider submissions. Each run, case, and submission is stored under its own key. Workflow evaluations do not require any Braintrust backend changes.

The API for this interface is not yet stabilized and may change or be removed across non-major versions. Functionality is not guaranteed.