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

# Content Parts

> How Galtea stores the files and other parts in the content list of a trace or test case input

> [!WARNING]
>
> You are reading the docs of Galtea 5.17. [Read this page in the latest version](https://docs.galtea.ai/concepts/product/version/session/content-parts.md).

## What are Content Parts?

A trace input, a trace output and a test case input can be an object with a `content` list. Each element of that list is a **content part**: a text, an image, a file or an audio clip. A part names its kind in its `type` field.

```json theme={"system"}
{
  "user_message": "Summarize this contract",
  "content": [
    { "type": "text", "text": "Focus on the payment terms." },
    { "type": "file", "uri": "s3://bucket/files/org_123/2f6c0a9e41b84d7f9c3e5a1b2d4f6e80.pdf" },
    { "type": "file", "uri": "https://cdn.example.com/files/acme/report.pdf" }
  ]
}
```

Galtea decides for each element of the list on its own whether it is a Galtea file, and checks and stores each element on its own.

## Galtea Files

A **Galtea file** is a file you uploaded to Galtea, or one that Galtea stored from inline media in a trace. Galtea knows it by its **key**, the storage name that the upload or the copy gives it. The key has this shape: `files/<organization id>/<32 lowercase hex characters>.<extension>`.

A `file` part is a Galtea file when the path of its `uri` is that key. The path can also start with one extra segment, the storage bucket or container. Galtea reads the key on any host, and also in a signed URL. The URI that [`galtea.storage.upload()`](https://docs.galtea.ai/v5.17/sdk/api/storage/upload) returns with the default `file_type` is a Galtea file. So is any URL that Galtea returns for a Galtea file, even when its path has more segments before the key. In the example above, the second part is a Galtea file and the third part is not. See [Audio Parts](#audio-parts) for audio, which follows its own rules.

To get a key, upload the file with the SDK or attach it in the dashboard. The SDK `input_file_paths` and `output_file_paths` parameters upload a local file for you. See [Upload File](https://docs.galtea.ai/v5.17/sdk/api/storage/upload.md).

When you attach a Galtea `file` part of your organization, Galtea does these things:

* It stores the `uri` without its upload signature, so the reference you read back never expires.
* It fills `mimeType` from the stored file when you leave it out, and `filename` too where the storage keeps the name. It always reads `sizeBytes` from the stored file.
* It checks the file type. A type that is not accepted fails with the message `"<name>" is not an accepted file type.` The accepted types are listed in [File inputs](https://docs.galtea.ai/v5.17/concepts/product/dataset/test-case.md#file-inputs).
* It checks the limits: at most 20 files and 20 MB in total for one input or one output.

## Your Own Parts

Every element that is not a Galtea file is yours. Galtea stores it exactly as you sent it. This includes:

* A `text` part.
* An `image_url` part.
* A `file` part that names an OpenAI `file_id`.
* An element with no `type`.
* A file URL on your own host, such as `https://cdn.example.com/files/acme/report.pdf`.

Galtea does not fetch a URL on your own host when it stores one of these elements. A run sends only Galtea files to your endpoint, through `input_files`. Your own `file` parts are left out of `input_files`, and the turn runs without them. A file that an endpoint connection returns in its response follows other rules: see [Files in the Response](https://docs.galtea.ai/v5.17/concepts/product/endpoint-connection-configuration.md#files-in-the-response).

The SDK lists every `file` part that has a `uri` in `.input_files` and `.actual_output_files`, your own included. Only a Galtea file can be fetched with [`galtea.storage.download()`](https://docs.galtea.ai/v5.17/sdk/api/storage/download) or [`galtea.storage.read()`](https://docs.galtea.ai/v5.17/sdk/api/storage/read). For any other URL the platform answers that the file is not found, so fetch it with your own client.

## What Happens to Each Element

| Element | Test case input | Trace input | Trace output |
| - | - | - | - |
| Galtea `file` part of your organization | Stored without its signature, details filled, checked | Same | Same |
| Galtea `file` part of another organization | Refused with a `400` | Refused with a `400` | Refused with a `400` |
| Galtea `file` part that no longer exists in storage | Refused with a `400` | Stored without its signature or its `sizeBytes` | Stored without its signature or its `sizeBytes` |
| Your own part | Stored as sent | Stored as sent, except inline media where the copy is on | Stored as sent, except inline media where the copy is on |

The trace columns also hold for the input and output of a span. In a batch of spans, a span with a Galtea file of another organization is refused on its own and the other spans are stored.

On a deployment that sets the API variable `INLINE_MEDIA_COPY_ENABLED` to `true`, Galtea replaces inline media in a trace input or output with a Galtea file token, and stores the file. Inline media is a binary `data:` URI, or the byte field of a provider object: an Anthropic `base64` source, a Gemini `inline_data`, a Vertex `media` part, a Bedrock `source.bytes`, an OpenTelemetry `blob`, a Vercel AI SDK `file` or `image` part, or an MCP `image`, `audio` or `resource` blob. A byte field may hold base64, a `data:` URI or a Python bytes literal (`b'...'`), but a Python bytes literal inside JSON held in a string stays as sent. Text, files under about 768 bytes (1,024 base64 characters), files of a type Galtea does not detect, and files over 20 MB stay as sent. The copy applies to every trace write: traces sent with or without a turn id, span writes, and a trace file import. It does not apply to a test case input. The copy is off by default. The dashboard shows each token in a trace or span input or output as the file it names, with the same preview and download controls as an uploaded file. The **Raw** view shows the token as stored. When a run sends an earlier turn to your endpoint again, for example in `past_turns`, Galtea puts the stored file back, even after the copy is turned off. A `data:` URI comes back as a `data:` URI. A byte field comes back as base64, also when you sent a `data:` URI or a bytes literal in it. When the stored file is missing or over 20 MB, your endpoint receives the `@@@galtea-file:...@@@` token text in its place. The restored text of one request to your endpoint, past turns included, is at most 50 MB. Past that, the session fails and your endpoint does not receive the turn. Past turns reach your agent with their inline media restored from SDK 5.17.0; an earlier SDK passes the stored file token. The same 50 MB limit holds for each turn the SDK rebuilds: past it, the API answers `400` and the run fails, where an earlier SDK went on with the token. A read through the API or the SDK returns the stored token text, unless it asks for `restoreFiles` (`restore_files` in the SDK). An evaluation judge reads `[File N]` in place of the token, with N the file's number in the session, and a stored image or PDF counts as a Galtea file: see [Files and Evaluation](#files-and-evaluation).

An edit that keeps a Galtea file unchanged does not read storage again. So the edit succeeds even when someone deleted the file after you attached it.

## Audio Parts

Galtea does not apply the file checks above to an `audio` part. It does not check its type, its size or the file count. On a test case input, an `audio` part needs a `transcript`.

## Files and Evaluation

Only a Galtea file is sent to the judge, the model that scores a metric. A file that Galtea stored from inline media counts as a Galtea file when it is an image or a PDF. A stored audio or other file reads as `[File N]` text and never makes the evaluator skip a metric. The judge reads each element of a `content` list in its place: a Galtea file as `[File N]`, a text part as its text, an audio part as its transcript, and any other element, a file on your own host included, as its JSON text. A file on your own host is never sent as a file, so it never makes the evaluator skip a metric. Galtea numbers the files of a session in one sequence: turn files first, in turn order, input before output, then the files of every span. A file that sits in several places of a session, as a `file` part or as a token, takes one number, and the judge receives it once. The session page shows the same `File N` beside each turn file. The API check that a metric has text to read is separate: it counts every `file` part as a file, yours included. Most deployments do not send files to the judge yet: see [File inputs](https://docs.galtea.ai/v5.17/concepts/product/dataset/test-case.md#file-inputs) for which metrics Galtea skips when a turn carries a Galtea file.

## SDK Checks

In the SDK, each entry of `input_file_paths` and `output_file_paths` is a local path or a Galtea file reference, such as the `uri` of a Galtea file in `trace.input_files`. A URL whose path does not end in a Galtea key, such as `https://cdn.example.com/files/acme/report.pdf`, raises a `ValueError` before the SDK uploads anything. To keep a file on your own host, put its URL in a `file` part of `input` or `output` yourself.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.