> ## Documentation Index
> Fetch the complete documentation index at: https://www.getmaxim.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Attachments

> Learn how to attach files and URLs to traces and spans for richer observability in Maxim. Attachments let you add files (audio, images, text, etc.) or URLs to your traces and spans, providing extra context for debugging, analytics, and audit trails.

<Warning>
  * This feature is currently in beta.
  * Requires `maxim-py` >= 3.9.x
</Warning>

## Overview

Attachments let you add files (audio, images, text, etc.) or URLs to your traces and spans in Maxim. This provides extra context for debugging, analytics, and audit trails. All attachments are stored and viewable in the Maxim UI alongside your trace data.

## How to Add Attachments

You can attach files or URLs to both traces and spans. There are three main types of attachments:

| Attachment Type      | Use For                      | Example Parameter(s)               |
| -------------------- | ---------------------------- | ---------------------------------- |
| `FileAttachment`     | Local files (audio, images)  | `path`                             |
| `UrlAttachment`      | Remote files or images       | `url`, `mime_type` (optional)      |
| `FileDataAttachment` | Data blobs (bytes in memory) | `data`, `name`, `mime_type` (opt.) |

### Example: Add Attachments to a Trace

<CodeGroup>
  ```typescript JS/TS theme={null}
  // Create a new trace
  const trace = logger.trace({ id: uuid() });
  trace.input("test input");

  // Attach a local file
  trace.addAttachment({
  	id: uuid(),
  	type: "file",
  	path: "./files/wav_audio.wav",
  });

  // Attach a remote file or image by URL
  trace.addAttachment({
  	id: uuid(),
  	type: "url",
  	url: "https://sample-image.com/test-image",
  });

  // Attach a data blob (e.g., in-memory text)
  trace.addAttachment({
  	id: uuid(),
  	type: "fileData",
  	name: "greeting.txt",
  	data: Buffer.from("Hello world"),
  	mimeType: "text/plain",
  });
  ```

  ```python Python theme={null}
  from uuid import uuid4
  from maxim.logger import FileAttachment, UrlAttachment, FileDataAttachment

  # Create a new trace
  trace = logger.trace({'id': str(uuid4())})
  trace.set_input('test input')

  # Attach a local file
  trace.add_attachment(FileAttachment(path='./files/wav_audio.wav'))

  # Attach a remote file or image by URL
  trace.add_attachment(UrlAttachment(url='https://sample-image.com/test-image'))

  # Attach a data blob (e.g., in-memory text)
  trace.add_attachment(FileDataAttachment(data=b'Hello World', name='greeting.txt'))
  ```
</CodeGroup>

**Tip:**
You can also add attachments to a `span` or `generation` by replacing `trace` with your span or generation object.

## Notes

* You can provide a custom name for each file by passing the `name` property.
* Attachments are visible in the Maxim UI for each trace or span.
* The server detects the MIME type automatically, but you can override it by passing the `mime_type` parameter.

## Best Practices

* **File size limit:** Each file must be under 50 MB.
* **MIME type:** Maxim detects MIME type on the server, but you can override it if needed.
* **Name:** Add names to each file to easily detect them while surfing through logs.

***

If you have further questions, contact support.