Skip to main content
Attachments let you log binary data like images, audio, video, PDFs, and large JSON objects alongside your traces. This enables multimodal evaluations, preserves visual context, and handles data structures that exceed standard trace limits.

​
Upload files

Create an Attachment object with a file path or in-memory buffer. The SDK uploads attachments in the background without affecting logging latency. 
import { Attachment, initLogger } from "braintrust";

const logger = initLogger({ projectName: "My Project" });

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 attachments anywhere in log data - nested in objects, in arrays, or at the top level.

​
Log large JSON data

For JSON objects exceeding the 6MB trace limit, use JSONAttachment. This is ideal for conversation transcripts, document collections, or complex nested structures. 
import { JSONAttachment, initLogger } from "braintrust";

const logger = initLogger({ projectName: "My Project" });

// 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: {
    transcript: new JSONAttachment(transcript, {
      filename: "conversation_transcript.json",
      pretty: true, // Optional: pretty-print
    }),
  },
  output: "Conversation completed",
});
JSON attachments bypass the 6MB limit and aren’t indexed, saving storage and speeding ingestion while remaining fully viewable in the UI.
External attachments are only supported in self-hosted deployments, not in Braintrust cloud.
Reference files in external object stores (currently S3 only) without uploading them: 
import { ExternalAttachment, initLogger } from "braintrust";

const logger = initLogger({ projectName: "My Project" });

logger.log({
  input: {
    document: new ExternalAttachment({
      url: "s3://my-bucket/path/to/file.pdf",
      filename: "file.pdf",
      contentType: "application/pdf",
    }),
  },
  output: "Document processed",
});

​
Next steps