> ## Documentation Index > Fetch the complete documentation index at: https://www.braintrust.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Braintrust TypeScript SDK > TypeScript API reference for Braintrust SDK v3.39.0 This page provides a complete, auto-generated reference for the Braintrust TypeScript SDK. For usage guidance on important APIs, see the [API Reference](/docs/sdks/typescript/api-reference). Also see the [Braintrust TypeScript SDK](https://github.com/braintrustdata/braintrust-sdk-javascript) on GitHub. ## Installation ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} npm install braintrust ``` ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pnpm add braintrust ``` > [!NOTE] > > 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 **headers** `Record` **url** `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. **callback** `AgentAssertionScorerCallback` **options** `Object` **options.name** `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). **options** `Object` **options.name** `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. **options** `Object` **options.defineState** `EveDefineState` *required* **options.metadata** `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. **options** `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. **event** `unknown` **ctx** `unknown` ### BraintrustMiddleware Creates a Braintrust middleware for AI SDK v2 that automatically traces generateText and streamText calls with comprehensive metadata and metrics. **config** `MiddlewareConfig` Configuration options for the middleware ### buildLocalSummary buildLocalSummary function **evaluator** `EvaluatorDef` **evaluator.evalName** `string` *required* **evaluator.projectName** `string` *required* **evaluator.baseExperimentId** `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. **evaluator.baseExperimentName** `string` An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment. **evaluator.classifiers** `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. **evaluator.data** `EvalData` *required* A function that returns a list of inputs, expected outputs, and metadata. **evaluator.description** `string` An optional description for the experiment. **evaluator.errorScoreHandler** `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. **evaluator.experimentName** `string` An optional name for the experiment. **evaluator.flushBeforeScoring** `boolean` Flushes spans before calling scoring functions **evaluator.gitMetadataSettings** `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. **evaluator.isPublic** `boolean` Whether the experiment should be public. Defaults to false. **evaluator.maxConcurrency** `number` The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency. **evaluator.metadata** `Record` Optional additional metadata for the experiment. **evaluator.parameters** `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\ from loadParameters() **evaluator.projectId** `string` If specified, uses the given project ID instead of the evaluator's name to identify the project. **evaluator.repoInfo** `null | Object` Optionally explicitly specify the git metadata for this experiment. This takes precedence over `gitMetadataSettings` if specified. **evaluator.scores** `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. **evaluator.signal** `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. **evaluator.state** `BraintrustState` If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key). **evaluator.summarizeScores** `boolean` Whether to summarize the scores of the experiment after it has run. Defaults to true. **evaluator.tags** `string[]` Optional tags for the experiment. **evaluator.task** `EvalTask` *required* A function that takes an input and returns an output. **evaluator.timeout** `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`. **evaluator.trialCount** `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. **evaluator.update** `boolean` Whether to update an existing experiment with `experiment_name` if one exists. Defaults to false. **results** `EvalResult[]` **precomputedScores** `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. **stream** `T` 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. **args** `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. **args** `CompleteOpenAIBatchTraceArgs` ### configureInstrumentation Configure auto-instrumentation. This must be called before importing any AI SDKs to take effect. **config** `InstrumentationConfig` **config.integrations** `InstrumentationIntegrationsConfig` Configuration for individual SDK integrations. Set to false to disable instrumentation for that SDK. **config.spanCustomizers** `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. **config.streamingAttachmentBufferBytes** `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. 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 **key** `string` ### createFinalValuePassThroughStream Create a stream that passes through the final value of the stream. This is used to implement `BraintrustStream.finalValue()`. **onFinal** `Object` A function to call with the final value of the stream. **onError** `Object` ### currentExperiment Returns the currently-active experiment (set by [`init`](#init)). Returns undefined if no current experiment has been set. **options** `OptionalStateArg` ### currentLogger Returns the currently-active logger (set by [`initLogger`](#initlogger)). Returns undefined if no current logger has been set. **options** `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`](#span) for full details. **options** `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. **definition** `DatasetPipelineDefinition` ### deepCopyEvent Creates a deep copy of the given event. Replaces references to user objects with placeholder strings to ensure serializability, except for [`Attachment`](#attachment) and [`ExternalAttachment`](#externalattachment) objects, which are preserved and not deep-copied. **event** `T` ### defaultErrorScoreHandler defaultErrorScoreHandler function **args** `Object` **args.data** `EvalCase` *required* **args.rootSpan** `Span` *required* **args.unhandledScores** `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. **projectName** `string` **evaluator** `WorkflowEvaluator` ### deserializePlainStringAsJSON deserializePlainStringAsJSON function **s** `string` ### devNullWritableStream devNullWritableStream function ### Eval Eval function **name** `string` **evaluator** `Evaluator` **evaluator.baseExperimentId** `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. **evaluator.baseExperimentName** `string` An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment. **evaluator.classifiers** `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. **evaluator.data** `EvalData` *required* A function that returns a list of inputs, expected outputs, and metadata. **evaluator.description** `string` An optional description for the experiment. **evaluator.errorScoreHandler** `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. **evaluator.experimentName** `string` An optional name for the experiment. **evaluator.flushBeforeScoring** `boolean` Flushes spans before calling scoring functions **evaluator.gitMetadataSettings** `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. **evaluator.isPublic** `boolean` Whether the experiment should be public. Defaults to false. **evaluator.maxConcurrency** `number` The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency. **evaluator.metadata** `Record` Optional additional metadata for the experiment. **evaluator.parameters** `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\ from loadParameters() **evaluator.projectId** `string` If specified, uses the given project ID instead of the evaluator's name to identify the project. **evaluator.repoInfo** `null | Object` Optionally explicitly specify the git metadata for this experiment. This takes precedence over `gitMetadataSettings` if specified. **evaluator.scores** `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. **evaluator.signal** `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. **evaluator.state** `BraintrustState` If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key). **evaluator.summarizeScores** `boolean` Whether to summarize the scores of the experiment after it has run. Defaults to true. **evaluator.tags** `string[]` Optional tags for the experiment. **evaluator.task** `EvalTask` *required* A function that takes an input and returns an output. **evaluator.timeout** `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`. **evaluator.trialCount** `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. **evaluator.update** `boolean` Whether to update an existing experiment with `experiment_name` if one exists. Defaults to false. **reporterOrOpts** `string | ReporterDef | EvalOptions` ### extractTraceContextFromHeaders Extract an opaque W3C trace-context from inbound request headers. This is the receive-side counterpart of `Span.inject` / [`injectTraceContext`](#injecttracecontext). The return value is an opaque propagation context that can be passed as `parent` to `startSpan`: ```ts theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} const ctx = extractTraceContextFromHeaders(request.headers); traced((span) => { ... }, { 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. **headers** `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. **token** `OpenAIAgentsTraceToken` **error** `unknown` ### flush Flush any pending rows to the server. **options** `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. **projectId** `string` The ID of the project to query **promptId** `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`](#extracttracecontextfromheaders)). **options** `unknown` **options.parent** `string | PropagationContext` ### getTemplateRenderer Gets an active template renderer by name. Returns `undefined` if the renderer is not active. **name** `string` Name of the renderer to retrieve ### init Log in, and then initialize a new experiment in a specified project. If the project does not exist, it will be created. **options** `Readonly` Options for configuring init(). **options.project** `string` **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` **options.baseExperiment** `string` **options.baseExperimentId** `string` **options.dataset** `AnyDataset | DatasetRef` **options.description** `string` **options.experiment** `string` **options.gitMetadataSettings** `GitMetadataSettingsType` **options.isPublic** `boolean` **options.metadata** `Record` **options.parameters** `ParametersRef | RemoteEvalParameters` **options.projectId** `string` **options.repoInfo** `RepoInfoType` **options.setCurrent** `boolean` **options.state** `BraintrustState` **options.tags** `string[]` **options.update** `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. **options** `Readonly` Options for configuring initDataset(). **options.project** `string` **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` **options.dataset** `string` **options.datasetId** `string` **options.description** `string` **options.environment** `string` **options.metadata** `Record` **options.projectId** `string` **options.snapshotName** `string` **options.state** `BraintrustState` **options.version** `string` ### initExperiment Alias for init(options). **options** `Readonly` **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` **options.baseExperiment** `string` **options.baseExperimentId** `string` **options.dataset** `AnyDataset | DatasetRef` **options.description** `string` **options.experiment** `string` **options.gitMetadataSettings** `GitMetadataSettingsType` **options.isPublic** `boolean` **options.metadata** `Record` **options.parameters** `ParametersRef | RemoteEvalParameters` **options.projectId** `string` **options.repoInfo** `RepoInfoType` **options.setCurrent** `boolean` **options.state** `BraintrustState` **options.tags** `string[]` **options.update** `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: ```ts theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} const myFunction = initFunction({projectName: "myproject", slug: "myfunction"}); await Eval("test", { task: myFunction, data: testData, scores: [...] }); ``` When used as a scorer: ```ts theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} const myScorer = initFunction({projectName: "myproject", slug: "myscorer"}); await Eval("test", { task: someTask, data: testData, scores: [myScorer] }); ``` **options** `Object` Options for the function. **options.projectName** `string` *required* The project name containing the function. **options.slug** `string` *required* The slug of the function to invoke. **options.state** `BraintrustState` Optional Braintrust state to use. **options.version** `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. **options** `Readonly` Additional options for configuring init(). **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` **options.environment** `SpanOriginEnvironment` **options.orgProjectMetadata** `OrgProjectMetadata` **options.projectId** `string` **options.projectName** `string` **options.setCurrent** `boolean` **options.state** `BraintrustState` ### initNodeTestSuite Creates a new Node.js test suite with Braintrust experiment tracking. **config** `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`](#extracttracecontextfromheaders). If no span is provided, the currently-active span is used. Propagation is best-effort and never throws. **carrier** `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. **options** `unknown` **options.span** `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. **args** `unknown` The arguments for the function (see [`InvokeFunctionArgs`](#invokefunctionargs) for more details). **args.functionType** `"tag" | "scorer" | "task" | "tool" | "custom_view" | "preprocessor" | "facet" | "classifier" | "parameters" | "sandbox" | "llm"` The type of the global function to invoke. If unspecified, defaults to 'scorer' for backward compatibility. **args.function\_id** `string` The ID of the function to invoke. **args.globalFunction** `string` The name of the global function to invoke. **args.input** `Input` *required* The input to the function. This will be logged as the `input` field in the span. **args.messages** `Object | Object | Object | Object | Object | Object | Object[]` Additional OpenAI-style messages to add to the prompt (only works for llm functions). **args.metadata** `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 and as the `metadata` argument to the function. **args.mode** `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. **args.overrides** `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. **args.parent** `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. **args.projectId** `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. **args.projectName** `string` The name of the project containing the function to invoke. **args.promptSessionFunctionId** `string` The ID of the function in the prompt session to invoke. **args.promptSessionId** `string` The ID of the prompt session to invoke the function from. **args.schema** `unknown` A Zod schema to validate the output of the function and return a typed value. This is only used if `stream` is false. **args.slug** `string` The slug of the function to invoke. **args.state** `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. **args.stream** `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. **args.strict** `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. **args.tags** `string[]` Tags to add to the span. This will be logged as the `tags` field in the span. **args.version** `string` The version of the function to invoke. **args.apiKey** `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. **args.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **args.debugLogLevel** `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. **args.disableSpanCache** `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. **args.fetch** `Object` A custom fetch implementation to use. **args.noExitFlush** `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. **args.onFlushError** `Object` Calls this function if there's an error in the background flusher. **args.orgName** `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. **args.forceLogin** `boolean` ### isTemplateFormat isTemplateFormat function **v** `unknown` ### loadParameters Load parameters from the specified project. **options** `LoadParametersByProjectNameOptions` Options for configuring loadParameters(). ### loadPrompt Load a prompt from the specified project. **options** `LoadPromptOptions` Options for configuring loadPrompt(). **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` **options.defaults** `DefaultPromptArgs` **options.environment** `string` **options.id** `string` **options.noTrace** `boolean` **options.projectId** `string` **options.projectName** `string` **options.slug** `string` **options.state** `BraintrustState` **options.version** `string` ### log Log a single event to the current experiment. The event will be batched and uploaded behind the scenes. **event** `ExperimentLogFullArgs` The event to log. See `Experiment.log` for full details. **event.input** `unknown` *required* **event.id** `string` *required* ### logError logError function **span** `Span` **span.id** `string` *required* Row ID of the span. **span.kind** `"span"` *required* **span.rootSpanId** `string` *required* Root span ID of the span. **span.spanId** `string` *required* Span ID of the span. **span.spanParents** `string[]` *required* Parent span IDs of the span. **error** `unknown` ### login Log into Braintrust. This will prompt you for your API token, which you can find at [https://www.braintrust.dev/app/token](https://www.braintrust.dev/app/token). This method is called automatically by `init()`. **options** `unknown` Options for configuring login(). **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` 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 **options** `LoginOptions` **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **batches** `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. **files** `OpenAIFilesResource` ### parseCachedHeader parseCachedHeader function **value** `undefined | null | string` ### parseTemplateFormat parseTemplateFormat function **value** `unknown` **defaultFormat** `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. **slug** `string` The identifier generated from `Span.export`. **opts** `Object` Optional arguments. **opts.appUrl** `string` The app URL to use. If not provided, the app URL will be inferred from the state. **opts.orgName** `string` The org name to use. If not provided, the org name will be inferred from the state. **opts.state** `BraintrustState` The login state to use. If not provided, the global state will be used. ### pickLogs3OverflowObjectIds pickLogs3OverflowObjectIds function **row** `Record` ### promptDefinitionToPromptData promptDefinitionToPromptData function **promptDefinition** `unknown` **promptDefinition.environments** `string[]` **promptDefinition.model** `string` *required* **promptDefinition.params** `objectOutputType | objectOutputType | objectOutputType | objectOutputType | objectOutputType` **promptDefinition.templateFormat** `"none" | "mustache" | "nunjucks"` **rawTools** `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). **callback** `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. **plugin** `TemplateRendererPlugin` **plugin.createRenderer** `Object` *required* Factory function that creates a renderer instance. **plugin.defaultOptions** `unknown` Default configuration options for this plugin. **plugin.name** `string` *required* Unique identifier for this plugin. Must match the format string used in `templateFormat` option. ### renderMessage renderMessage function **render** `Object` **message** `T` ### renderPromptParams renderPromptParams function **params** `undefined | objectOutputType | objectOutputType | objectOutputType | objectOutputType | objectOutputType` **args** `Record` **options** `Object` **options.strict** `boolean` **options.templateFormat** `TemplateFormat` ### renderTemplateContent renderTemplateContent function **template** `string` **variables** `Record` **escape** `Object` **options** `Object` **options.strict** `boolean` **options.templateFormat** `TemplateFormat` ### Reporter Reporter function **name** `string` **reporter** `ReporterBody` ### reportFailures reportFailures function **evaluator** `EvaluatorDef` **evaluator.evalName** `string` *required* **evaluator.projectName** `string` *required* **evaluator.baseExperimentId** `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. **evaluator.baseExperimentName** `string` An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment. **evaluator.classifiers** `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. **evaluator.data** `EvalData` *required* A function that returns a list of inputs, expected outputs, and metadata. **evaluator.description** `string` An optional description for the experiment. **evaluator.errorScoreHandler** `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. **evaluator.experimentName** `string` An optional name for the experiment. **evaluator.flushBeforeScoring** `boolean` Flushes spans before calling scoring functions **evaluator.gitMetadataSettings** `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. **evaluator.isPublic** `boolean` Whether the experiment should be public. Defaults to false. **evaluator.maxConcurrency** `number` The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency. **evaluator.metadata** `Record` Optional additional metadata for the experiment. **evaluator.parameters** `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\ from loadParameters() **evaluator.projectId** `string` If specified, uses the given project ID instead of the evaluator's name to identify the project. **evaluator.repoInfo** `null | Object` Optionally explicitly specify the git metadata for this experiment. This takes precedence over `gitMetadataSettings` if specified. **evaluator.scores** `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. **evaluator.signal** `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. **evaluator.state** `BraintrustState` If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key). **evaluator.summarizeScores** `boolean` Whether to summarize the scores of the experiment after it has run. Defaults to true. **evaluator.tags** `string[]` Optional tags for the experiment. **evaluator.task** `EvalTask` *required* A function that takes an input and returns an output. **evaluator.timeout** `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`. **evaluator.trialCount** `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. **evaluator.update** `boolean` Whether to update an existing experiment with `experiment_name` if one exists. Defaults to false. **failingResults** `EvalResult[]` **\_\_namedParameters** `ReporterOpts` ### runEvaluator runEvaluator function **experiment** `null | Experiment` **evaluator** `EvaluatorDef` **evaluator.evalName** `string` *required* **evaluator.projectName** `string` *required* **evaluator.baseExperimentId** `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. **evaluator.baseExperimentName** `string` An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment. **evaluator.classifiers** `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. **evaluator.data** `EvalData` *required* A function that returns a list of inputs, expected outputs, and metadata. **evaluator.description** `string` An optional description for the experiment. **evaluator.errorScoreHandler** `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. **evaluator.experimentName** `string` An optional name for the experiment. **evaluator.flushBeforeScoring** `boolean` Flushes spans before calling scoring functions **evaluator.gitMetadataSettings** `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. **evaluator.isPublic** `boolean` Whether the experiment should be public. Defaults to false. **evaluator.maxConcurrency** `number` The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency. **evaluator.metadata** `Record` Optional additional metadata for the experiment. **evaluator.parameters** `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\ from loadParameters() **evaluator.projectId** `string` If specified, uses the given project ID instead of the evaluator's name to identify the project. **evaluator.repoInfo** `null | Object` Optionally explicitly specify the git metadata for this experiment. This takes precedence over `gitMetadataSettings` if specified. **evaluator.scores** `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. **evaluator.signal** `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. **evaluator.state** `BraintrustState` If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key). **evaluator.summarizeScores** `boolean` Whether to summarize the scores of the experiment after it has run. Defaults to true. **evaluator.tags** `string[]` Optional tags for the experiment. **evaluator.task** `EvalTask` *required* A function that takes an input and returns an output. **evaluator.timeout** `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`. **evaluator.trialCount** `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. **evaluator.update** `boolean` Whether to update an existing experiment with `experiment_name` if one exists. Defaults to false. **progressReporter** `ProgressReporter` **filters** `Filter[]` **stream** `undefined | Object` **parameters** `InferParameters` **collectResults** `boolean` **enableCache** `boolean` ### setFetch Set the fetch implementation to use for requests. You can specify it here, or when you call `login`. **fetch** `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. **maskingFunction** `null | Object` A function that takes a JSON-serializable object and returns a masked version. Set to null to disable masking. ### spanComponentsToObjectId spanComponentsToObjectId function **\_\_namedParameters** `Object` **\_\_namedParameters.components** `SpanComponentsV3` *required* **\_\_namedParameters.state** `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. **args** `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. **args** `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`](#traced) for full details. **args** `unknown` **args.event** `StartSpanEventArgs` **args.name** `string` **args.parent** `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`](#extracttracecontextfromheaders)). **args.parentSpanIds** `ParentSpanIds | MultiParentSpanIds` **args.propagatedEvent** `StartSpanEventArgs` **args.spanAttributes** `Record` **args.spanId** `string` **args.startTime** `number` **args.type** `SpanType` ### summarize Summarize the current experiment, including the scores (compared to the closest reference experiment) and metadata. **options** `Object` Options for summarizing the experiment. **options.comparisonExperimentId** `string` The experiment to compare against. If None, the most recent experiment on the origin's main branch will be used. **options.summarizeScores** `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. **fn** `F` **args** `unknown` **args.event** `StartSpanEventArgs` **args.name** `string` **args.parent** `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`](#extracttracecontextfromheaders)). **args.parentSpanIds** `ParentSpanIds | MultiParentSpanIds` **args.propagatedEvent** `StartSpanEventArgs` **args.spanAttributes** `Record` **args.spanId** `string` **args.startTime** `number` **args.type** `SpanType` **args.setCurrent** `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. **callback** `Object` **args** `unknown` **args.event** `StartSpanEventArgs` **args.name** `string` **args.parent** `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`](#extracttracecontextfromheaders)). **args.parentSpanIds** `ParentSpanIds | MultiParentSpanIds` **args.propagatedEvent** `StartSpanEventArgs` **args.spanAttributes** `Record` **args.spanId** `string` **args.startTime** `number` **args.type** `SpanType` **args.setCurrent** `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. **token** `OpenAIAgentsTraceToken` **event** `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. **\_\_namedParameters** `unknown` **\_\_namedParameters.exported** `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. **upload** `Object` The overflow upload metadata from the API **upload.fields** `Record` **upload.headers** `Record` **upload.key** `string` *required* **upload.method** `"POST" | "PUT"` *required* **upload.signedUrl** `string` *required* **payload** `string` The JSON payload string to upload **fetchFn** `Object` Optional custom fetch function (defaults to global fetch) ### utf8ByteLength utf8ByteLength function **value** `string` ### withCurrent Runs the provided callback with the span as the current span. **span** `Span` **span.id** `string` *required* Row ID of the span. **span.kind** `"span"` *required* **span.rootSpanId** `string` *required* Root span ID of the span. **span.spanId** `string` *required* Span ID of the span. **span.spanParents** `string[]` *required* Parent span IDs of the span. **callback** `Object` **state** `BraintrustState` ### withDataset withDataset function **project** `string` **callback** `Object` **options** `Readonly` **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` **options.dataset** `string` **options.datasetId** `string` **options.description** `string` **options.environment** `string` **options.metadata** `Record` **options.projectId** `string` **options.snapshotName** `string` **options.state** `BraintrustState` **options.version** `string` ### withExperiment withExperiment function **project** `string` **callback** `Object` **options** `Readonly` **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` **options.baseExperiment** `string` **options.baseExperimentId** `string` **options.dataset** `AnyDataset | DatasetRef` **options.description** `string` **options.experiment** `string` **options.gitMetadataSettings** `Object` **options.isPublic** `boolean` **options.metadata** `Record` **options.parameters** `ParametersRef | RemoteEvalParameters` **options.projectId** `string` **options.repoInfo** `null | Object` **options.setCurrent** `boolean` **options.state** `BraintrustState` **options.tags** `string[]` **options.update** `boolean` **options.setCurrent** `boolean` ### withLogger withLogger function **callback** `Object` **options** `Readonly` **options.apiKey** `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. **options.appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **options.debugLogLevel** `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. **options.disableSpanCache** `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. **options.fetch** `Object` A custom fetch implementation to use. **options.noExitFlush** `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. **options.onFlushError** `Object` Calls this function if there's an error in the background flusher. **options.orgName** `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. **options.forceLogin** `boolean` **options.environment** `SpanOriginEnvironment` **options.orgProjectMetadata** `OrgProjectMetadata` **options.projectId** `string` **options.projectName** `string` **options.setCurrent** `boolean` **options.state** `BraintrustState` **options.setCurrent** `boolean` ### withParent withParent function **parent** `string | PropagationContext` **callback** `Object` **state** `BraintrustState` ### wrapAgentClass wrapAgentClass function **AgentClass** `any` **options** `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. **aiSDK** `T` **options** `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 **model** `T` ### 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. **anthropic** `T` ### wrapBedrockRuntime Wrap an AWS Bedrock Runtime client with Braintrust tracing. **client** `T` ### 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. **sdk** `T` 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. **Agent** `T` ### 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. **module** `T` ### wrapCloudflareThink Adds Braintrust tracing to an `@cloudflare/think` module when build-time auto-instrumentation is unavailable. **sdk** `T` ### wrapCohere Wrap a Cohere client so method calls emit diagnostics-channel events that Braintrust plugins can consume. **cohere** `T` ### 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. **target** `LogConsole` **options** `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. **client** `T` ### wrapCursorSDK Wraps the Cursor TypeScript SDK with Braintrust tracing. The wrapper emits invocation hooks; the Cursor SDK plugin owns span lifecycle. **sdk** `T` ### 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. **client** `T` ### 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 **genkit** `T` ### 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. **adkModule** `T` 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. **googleGenAI** `T` The Google GenAI module ### wrapGoogleGenerativeAI Trace @google/generative-ai model and chat calls through Braintrust. **client** `T` ### wrapGroq Wrap a Groq client (created with `new Groq(...)`) with Braintrust tracing. **groq** `T` ### 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 **huggingFace** `HuggingFaceModule` ### wrapHuggingFaceTransformers wrapHuggingFaceTransformers function **transformers** `HuggingFaceTransformersModule` ### wrapLangGraphSDK Trace LangGraph Platform runs that the caller waits for or streams. **client** `T` ### wrapLangSmithClient wrapLangSmithClient function **namespace** `T` ### wrapLangSmithRunTrees wrapLangSmithRunTrees function **namespace** `T` ### wrapLangSmithTraceable wrapLangSmithTraceable function **namespace** `T` ### 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. With attachment capture enabled, the call audio is recorded as PCM attachments. Wrap the module before constructing sessions; only sessions created through the wrapped module are traced. **module** `T` ### wrapMastraAgent wrapMastraAgent function **agent** `T` **\_options** `Object` **\_options.name** `string` **\_options.span\_name** `string` ### wrapMistral Wrap a Mistral client (created with `new Mistral(...)`) with Braintrust tracing. **mistral** `T` ### wrapOllama Wrap an Ollama client so generation and embedding calls emit Braintrust diagnostics-channel events. **ollama** `T` ### 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. **openai** `T` ### wrapOpenAICodexSDK Wraps the OpenAI Codex TypeScript SDK with Braintrust tracing. The wrapper emits diagnostics-channel events; the OpenAI Codex plugin owns span lifecycle. **sdk** `T` ### wrapOpenAIv4 wrapOpenAIv4 function **openai** `T` ### wrapOpenRouter Wrap an OpenRouter client (created with `new OpenRouter(...)`) so calls emit diagnostics-channel events that Braintrust plugins can consume. **openrouter** `T` ### wrapOpenRouterAgent Wrap an @openrouter/agent OpenRouter client so callModel() emits diagnostics-channel events consumed by the OpenRouter Agent plugin. **agent** `T` ### wrapPiCodingAgentSDK Wraps the Pi Coding Agent SDK with Braintrust tracing. The wrapper emits instrumentation hook calls; the Pi Coding Agent plugin owns span lifecycle. **sdk** `T` ### wrapStrandsAgentSDK Wraps the Strands Agent SDK with Braintrust tracing. The wrapper invokes typed instrumentation channels; the Strands plugin owns span lifecycle. **sdk** `T` ### 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: ```ts theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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. **fn** `F` The function to wrap. **args** `unknown` Span-level arguments (e.g. a custom name or type) to pass to `traced`. **args.event** `StartSpanEventArgs` **args.name** `string` **args.parent** `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`](#extracttracecontextfromheaders)). **args.parentSpanIds** `ParentSpanIds | MultiParentSpanIds` **args.propagatedEvent** `StartSpanEventArgs` **args.spanAttributes** `Record` **args.spanId** `string` **args.startTime** `number` **args.type** `SpanType` **args.setCurrent** `boolean` ### wrapTypeSafe Wrap a TypeSafe client so systemOne calls pass through Braintrust tracing. **client** `T` ### 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** `VitestMethods` Object containing Vitest methods (test, describe, expect, etc.) **config** `WrapperConfig` Optional configuration object ### wrapVoyageAI Wrap a Voyage AI client so method calls pass through the Braintrust instrumentation hooks. **client** `T` ## 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 **reference** `Object` The object that replaces this `Attachment` at upload time. Methods `data()`, `debugInfo()`, `upload()` ### BaseAttachment BaseAttachment class Properties **reference** `Object | Object` Methods `data()`, `debugInfo()`, `upload()` ### BraintrustLangChainCallbackHandler BraintrustLangChainCallbackHandler class Properties **name** `string` Methods `endSpan()`, `handleAgentAction()`, `handleAgentEnd()`, `handleChainEnd()`, `handleChainError()`, `handleChainStart()`, `handleChatModelStart()`, `handleLLMEnd()`, `handleLLMError()`, `handleLLMNewToken()`, `handleLLMStart()`, `handleRetrieverEnd()`, `handleRetrieverError()`, `handleRetrieverStart()`, `handleToolEnd()`, `handleToolError()`, `handleToolStart()`, `startSpan()` ### BraintrustObservabilityExporter Translates Mastra `TracingEvent`s 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 **name** `"braintrust"` Methods `exportTracingEvent()`, `flush()`, `shutdown()` ### BraintrustState BraintrustState class Properties **apiUrl** `null | string` **appPublicUrl** `null | string` **appUrl** `null | string` **currentExperiment** `undefined | Experiment` **currentLogger** `undefined | Logger` **currentParent** `IsoAsyncLocalStorage` **currentSpan** `IsoAsyncLocalStorage` **debugLogLevel** `DebugLogLevel` **fetch** `Object` **gitMetadataSettings** `Object` **id** `string` **loggedIn** `boolean` **loginToken** `null | string` **orgId** `null | string` **orgName** `null | string` **parametersCache** `ParametersCache` **promptCache** `PromptCache` **proxyUrl** `null | string` **spanCache** `SpanCache` **spanOriginEnvironment** `undefined | SpanOriginEnvironment` **contextManager** `unknown` **idGenerator** `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 **description** `string` **handler** `Fn` **ifExists** `"error" | "ignore" | "replace"` **metadata** `Record` **name** `string` **parameters** `ZodSchema` **project** `Project` **returns** `ZodSchema` **slug** `string` **tags** `string[]` **type** `"tag" | "scorer" | "task" | "tool" | "custom_view" | "preprocessor" | "facet" | "classifier" | "parameters" | "sandbox" | "llm"` Methods `key()` ### CodePrompt CodePrompt class Properties **description** `string` **environmentSlugs** `string[]` **functionType** `"tag" | "scorer" | "task" | "tool" | "custom_view" | "preprocessor" | "facet" | "classifier" | "parameters" | "sandbox" | "llm"` **id** `string` **ifExists** `"error" | "ignore" | "replace"` **metadata** `Record` **name** `string` **project** `Project` **prompt** `Object` **slug** `string` **tags** `string[]` **toolFunctions** `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 **id** `unknown` **loggingState** `unknown` **name** `unknown` **project** `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 **results** `EvalResult[]` **summary** `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 **dataset** `AnyDataset` **kind** `"experiment"` **id** `unknown` **loggingState** `unknown` **name** `unknown` **project** `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 **reference** `Object` The object that replaces this `ExternalAttachment` at upload time. Methods `data()`, `debugInfo()`, `upload()` ### FailedHTTPResponse FailedHTTPResponse class Properties **cause** `unknown` **data** `string` **status** `number` **text** `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 **reference** `Object` The object that replaces this `Attachment` at upload time. Methods `data()`, `debugInfo()`, `upload()` ### LazyValue LazyValue class Properties **hasSucceeded** `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 **kind** `"logger"` **asyncFlush** `unknown` **id** `unknown` **loggingState** `unknown` **org\_id** `unknown` **project** `unknown` Methods `debug()`, `error()`, `export()`, `fatal()`, `flush()`, `fmt()`, `info()`, `log()`, `logFeedback()`, `startSpan()`, `trace()`, `traced()`, `updateSpan()`, `warn()` ### LoginInvalidOrgError LoginInvalidOrgError class Properties **message** `string` ### NoopSpan A fake implementation of the Span API which does nothing. This can be used as the default span. Properties **id** `string` Row ID of the span. **kind** `"span"` **rootSpanId** `string` Root span ID of the span. **spanId** `string` Span ID of the span. **spanParents** `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 **id** `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 **classifiers** `ClassifierBuilder` **id** `string` **name** `string` **parameters** `ParametersBuilder` **projectGroupName** `string` **prompts** `PromptBuilder` **scorers** `ScorerBuilder` **tools** `ToolBuilder` Methods `addCodeFunction()`, `addParameters()`, `addPrompt()`, `publish()` ### ProjectNameIdMap ProjectNameIdMap class Methods `getId()`, `getName()`, `resolve()` ### Prompt Prompt class Properties **id** `unknown` **name** `unknown` **options** `unknown` **projectId** `unknown` **prompt** `unknown` **promptData** `unknown` **slug** `unknown` **templateFormat** `unknown` **version** `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 **reference** `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 **id** `unknown` **loggingState** `unknown` **name** `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 **id** `unknown` Methods `[asyncIterator]()`, `clearCache()`, `fetch()`, `fetchedData()`, `getInternalBtql()`, `getPinnedVersion()`, `getState()`, `setPinnedVersion()`, `version()` ### SpanImpl Primary implementation of the `Span` interface. See [`Span`](#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 **kind** `"span"` **id** `unknown` Row ID of the span. **rootSpanId** `unknown` Root span ID of the span. **spanId** `unknown` Span ID of the span. **spanParents** `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 **kind** `"braintrust.workflow.scorer"` **name** `string` **processor** `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 **kind** `"braintrust.workflow.task"` **processor** `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 **kind** `"braintrust.workflow.scorer"` **name** `string` **processor** `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 **kind** `"braintrust.workflow.task"` **processor** `WorkflowSubmissionProcessor` ## Interfaces ### AttachmentParams AttachmentParams interface Properties **contentType** `string` **data** `string | Blob | ArrayBuffer` **filename** `string` **state** `BraintrustState` ### BackgroundLoggerOpts BackgroundLoggerOpts interface Properties **noExitFlush** `boolean` **onFlushError** `Object` ### ContextParentSpanIds ContextParentSpanIds interface Properties **rootSpanId** `string` **spanParents** `string[]` ### DatasetSummary Summary of a dataset's scores and metadata. Properties **dataSummary** `undefined | DataSummary` Summary of the dataset's data. **datasetName** `string` Name of the dataset. **datasetUrl** `string` URL to the experiment's page in the Braintrust app. **projectName** `string` Name of the project that the dataset belongs to. **projectUrl** `string` URL to the project's page in the Braintrust app. ### DataSummary Summary of a dataset's data. Properties **newRecords** `number` New or updated records added in this session. **totalRecords** `number` Total records in the dataset. ### EvalHooks EvalHooks interface Properties **expected** `Expected` The expected output for the current evaluation. **meta** `Object` **metadata** `unknown` The metadata object for the current evaluation. You can mutate this object to add or remove metadata. **parameters** `InferParameters` The current parameters being used for this specific task execution. Array parameters are converted to single values. **reportProgress** `Object` Report progress that will show up in the playground. **signal** `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** `Span` The task's span. **tags** `undefined | string[]` The tags for the current evaluation. **trialIndex** `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 **baseExperimentId** `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. **baseExperimentName** `string` An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment. **classifiers** `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. **data** `EvalData` A function that returns a list of inputs, expected outputs, and metadata. **description** `string` An optional description for the experiment. **errorScoreHandler** `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. **experimentName** `string` An optional name for the experiment. **flushBeforeScoring** `boolean` Flushes spans before calling scoring functions **gitMetadataSettings** `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. **isPublic** `boolean` Whether the experiment should be public. Defaults to false. **maxConcurrency** `number` The maximum number of tasks/scorers that will be run concurrently. Defaults to undefined, in which case there is no max concurrency. **metadata** `Record` Optional additional metadata for the experiment. **parameters** `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\ from loadParameters() **projectId** `string` If specified, uses the given project ID instead of the evaluator's name to identify the project. **repoInfo** `null | Object` Optionally explicitly specify the git metadata for this experiment. This takes precedence over `gitMetadataSettings` if specified. **scores** `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. **signal** `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. **state** `BraintrustState` If specified, uses the logger state to initialize Braintrust objects. If unspecified, falls back to the global state (initialized using your API key). **summarizeScores** `boolean` Whether to summarize the scores of the experiment after it has run. Defaults to true. **tags** `string[]` Optional tags for the experiment. **task** `EvalTask` A function that takes an input and returns an output. **timeout** `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`. **trialCount** `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. **update** `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 **comparisonExperimentName** `string` The experiment scores are baselined against. **experimentId** `string` ID of the experiment. May be `undefined` if the eval was run locally. **experimentName** `string` Name of the experiment. **experimentUrl** `string` URL to the experiment's page in the Braintrust app. **metrics** `Record` **projectId** `string` **projectName** `string` Name of the project that the experiment belongs to. **projectUrl** `string` URL to the project's page in the Braintrust app. **scores** `Record` Summary of the experiment's scores. ### Exportable Exportable interface ### ExternalAttachmentParams ExternalAttachmentParams interface Properties **contentType** `string` **filename** `string` **state** `BraintrustState` **url** `string` ### FunctionEvent FunctionEvent interface Properties **description** `string` **environments** `Object[]` **function\_data** `Object | Object | Object | Object | Object | Object | Object | Object | Object` **function\_type** `"tag" | "scorer" | "task" | "tool" | "custom_view" | "preprocessor" | "facet" | "classifier" | "parameters" | "sandbox" | "llm"` **if\_exists** `"error" | "ignore" | "replace"` **metadata** `Record` **name** `string` **project\_id** `string` **prompt\_data** `Object` **slug** `string` **tags** `string[]` ### GetThreadOptions Options for getThread(). Properties **preprocessor** `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 **integrations** `InstrumentationIntegrationsConfig` Configuration for individual SDK integrations. Set to false to disable instrumentation for that SDK. **spanCustomizers** `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. **streamingAttachmentBufferBytes** `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. 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. ### InvokeFunctionArgs Arguments for the `invoke` function. Properties **functionType** `"tag" | "scorer" | "task" | "tool" | "custom_view" | "preprocessor" | "facet" | "classifier" | "parameters" | "sandbox" | "llm"` The type of the global function to invoke. If unspecified, defaults to 'scorer' for backward compatibility. **function\_id** `string` The ID of the function to invoke. **globalFunction** `string` The name of the global function to invoke. **input** `Input` The input to the function. This will be logged as the `input` field in the span. **messages** `Object | Object | Object | Object | Object | Object | Object[]` Additional OpenAI-style messages to add to the prompt (only works for llm functions). **metadata** `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 and as the `metadata` argument to the function. **mode** `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. **overrides** `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. **parent** `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. **projectId** `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. **projectName** `string` The name of the project containing the function to invoke. **promptSessionFunctionId** `string` The ID of the function in the prompt session to invoke. **promptSessionId** `string` The ID of the prompt session to invoke the function from. **schema** `unknown` A Zod schema to validate the output of the function and return a typed value. This is only used if `stream` is false. **slug** `string` The slug of the function to invoke. **state** `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** `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. **strict** `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. **tags** `string[]` Tags to add to the span. This will be logged as the `tags` field in the span. **version** `string` The version of the function to invoke. ### LoginOptions Options for logging in to Braintrust. Properties **apiKey** `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. **appUrl** `string` The URL of the Braintrust App. Defaults to [https://www.braintrust.dev](https://www.braintrust.dev). You should not need to change this unless you are doing the "Full" deployment. **debugLogLevel** `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. **disableSpanCache** `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. **fetch** `Object` A custom fetch implementation to use. **noExitFlush** `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. **onFlushError** `Object` Calls this function if there's an error in the background flusher. **orgName** `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 **asyncFlush** `IsAsyncFlush` **computeMetadataArgs** `Record` **linkArgs** `LinkArgs` ### MastraObservabilityExporter Subset of the `ObservabilityExporter` contract from `@mastra/core`. Properties **name** `string` ### MetricSummary Summary of a metric's performance. Properties **diff** `number` Difference in metric between the current and reference experiment. **improvements** `number` Number of improvements in the metric. **metric** `number` Average metric across all examples. **name** `string` Name of the metric. **regressions** `number` Number of regressions in the metric. **unit** `string` Unit label for the metric. ### ObjectMetadata ObjectMetadata interface Properties **fullInfo** `Record` **id** `string` **name** `string` ### ParentExperimentIds ParentExperimentIds interface Properties **experiment\_id** `string` ### ParentProjectLogIds ParentProjectLogIds interface Properties **log\_id** `"g"` **project\_id** `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 **spanId** `string` **traceFlags** `string` **traceId** `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 **braintrustParent** `string` **traceFlags** `string` **tracestate** `string` ### ReporterBody ReporterBody interface ### ScoreSummary Summary of a score's performance. Properties **diff** `number` Difference in score between the current and reference experiment. **improvements** `number` Number of improvements in the score. **name** `string` Name of the score. **regressions** `number` Number of regressions in the score. **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 **id** `string` Row ID of the span. **kind** `"span"` **rootSpanId** `string` Root span ID of the span. **spanId** `string` Span ID of the span. **spanParents** `string[]` Parent span IDs of the span. ### SpanCustomizer SpanCustomizer interface ### SpanData Span data returned by getSpans(). Properties **input** `unknown` **metadata** `Record` **output** `unknown` **span\_attributes** `Object` **span\_id** `string` **span\_parents** `string[]` ### SpanDurationFilter Inclusive span duration bounds, in seconds. Properties **max** `number` Maximum value of metrics.end - metrics.start. **min** `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 **duration** `SpanDurationFilter` Bound how long the span took. **hasError** `boolean` Match spans based on whether they recorded an error. **metadata** `Record` Match metadata keys at any depth without type coercion. `null` matches a null or missing path. **name** `string[]` Match spans whose span\_attributes.name equals any of these. **spanType** `string[]` Match spans whose span\_attributes.type equals any of these. ### TemplateRenderer TemplateRenderer interface Properties **lint** `Object` **render** `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 **createRenderer** `Object` Factory function that creates a renderer instance. **defaultOptions** `unknown` Default configuration options for this plugin. **name** `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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.