Attachments

You can log arbitrary binary data, like images, audio, video, PDFs, and large JSON objects, as attachments. Attachments are useful for building multimodal evaluations, handling large data structures, and can enable advanced scenarios like summarizing visual content or analyzing document metadata.

Uploading attachments

You can upload attachments from either your code or the UI. Your files are securely stored in an object store and associated with the uploading user’s organization. Only you can access your attachments.

Via code

To upload an attachment, create a new Attachment object to represent the file path or in-memory buffer that you want to upload:

import { Attachment, initLogger } from "braintrust";   const logger = initLogger();   logger.log({  input: {  question: "What is this?",  context: new Attachment({  data: "path/to/input_image.jpg",  filename: "user_input.jpg",  contentType: "image/jpeg",  }),  },  output: "Example response.", });

You can place the Attachment anywhere in a log, dataset, or feedback log.

Behind the scenes, the Braintrust SDK automatically detects and uploads attachments in the background, in parallel to the original logs. This ensures that the latency of your logs isn’t affected by any additional processing.

Using external files as attachments

Braintrust also supports references to files in external object stores with the ExternalAttachment object. You can use this anywhere you would use an Attachment. Currently S3 is the only supported option for external files.

import { ExternalAttachment, initLogger } from "braintrust";   const logger = initLogger({ projectName: "ExternalAttachment Example" });   logger.log({  input: {  question: "What is this?",  additional_context: new ExternalAttachment({  url: "s3://an_existing_bucket/path/to/file.pdf",  filename: "file.pdf",  contentType: "application/pdf",  }),  },  output: "Example response.", });

Just like attachments uploaded to Braintrust, external attachments can be previewed and downloaded for local viewing.

JSON attachments

For large JSON objects that would bloat your trace size, you can use JSONAttachment. This is particularly useful for:

• Lengthy conversation transcripts
• Extensive document collections or knowledge bases
• Complex nested data structures with embeddings
• Large evaluation datasets
• Any JSON data that exceeds the 6MB trace limit

JSONAttachment automatically serializes your JSON data and stores it as an attachment with content type application/json. The data is:

• Uploaded separately as an attachment, bypassing the 6MB trace limit
• Not indexed, which saves storage space and speeds up ingestion
• Still fully viewable in the UI with all the features of the JSON viewer (collapsible nodes, syntax highlighting, search, etc.)

import { JSONAttachment, initLogger } from "braintrust";   const logger = initLogger();   // Example: Large conversation transcript const transcript = Array.from({ length: 100 }, (_, i) => ({  role: i % 2 === 0 ? "user" : "assistant",  content: `Message content ${i}...`,  timestamp: new Date().toISOString(), }));   logger.log({  input: {  type: "chat_completion",  // Store large transcript as an attachment  transcript: new JSONAttachment(transcript, {  filename: "conversation_transcript.json",  pretty: true, // Optional: pretty-print the JSON  }),  config: {  temperature: 0.7,  model: "gpt-5-mini",  },  },  output: "Completed conversation successfully", });

Just like other attachments, JSON attachments can be previewed directly in the UI and downloaded for local viewing. See the Uploading large traces section for more examples and details.

In the UI

You can upload attachments directly through the UI for any editable span field. This includes:

• Any dataset fields, including datasets in playgrounds
• Log span fields
• Experiment span fields

You can also include attachments in prompt messages when using models that support multimodal inputs.

Inline attachments

Sometimes your attachments are pre-hosted files which you do not want to upload explicitly, but would like to display as if they were attachments. Inline attachments allow you to do this, by specifying the URL and content type of the file. Create a JSON object anywhere in the log data with type: "inline_attachment" and src and content_type fields. The filename field is optional.

{  "file": {  "type": "inline_attachment",  "src": "https://robohash.org/example",  "content_type": "image/png",  "filename": "A robot"  } }

Viewing attachments

You can preview images, audio files, videos, PDFs, and JSON files in the Braintrust UI. You can also download any file to view it locally. We provide built-in support to preview attachments directly in playground input cells and traces.

In the playground, you can preview attachments in an inline embedded view for easy visual verification during experimentation:

In the trace pane, attachments appear as an additional list under the data viewer: