> ## 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.

# Upload Output File

> Upload a local file so it can be attached to a trace output.

> [!WARNING]
>
> You are reading the docs of Galtea 5.17. [Read this page in the latest version](https://docs.galtea.ai/sdk/api/trace/upload-output-file.md).

Use this when you build the trace output yourself. To attach files while logging a turn, pass `output_file_paths` to [Create Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/create.md), [Update Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/update.md) or [Create and Evaluate Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/create-and-evaluate.md) instead: it is shorter and does the same upload.

The one thing this method gives you that `output_file_paths` does not is reuse. Upload a document once and attach the same `AttachedFile` to many turns, rather than uploading it per turn.

This is the answer-side twin of [Upload Input File](https://docs.galtea.ai/v5.17/sdk/api/test-case/upload-input-file.md).

## Returns

Returns an `AttachedFile` with `uri`, `filename` and `mime_type`. Place it in the output's `content` list.

The `uri` still carries the upload's signature and expires. The API replaces it with a signature-free storage reference when the turn is written, so `trace.actual_output_files` reads back a uri that does not expire and grants nobody the bytes on its own. Never treat either form as a link to the bytes: ask for a fresh one 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).

> [!NOTE]
>
> `AttachedFile` is the object that used to be called `InputFile`, back when only an input could carry files. The same four fields now describe a file on either side. `InputFile` still works as a name for it, so code you already wrote keeps running, but it now warns with a `GalteaDeprecationWarning`. Switch to `AttachedFile` when you next touch that code.

## Example

```python theme={"system"}
lease = galtea.traces.upload_output_file("path/to/lease-agreement.pdf")

for question in ["Send me the lease again", "And a copy for my records"]:
    galtea.traces.create(
        session_id=session.id,
        input=question,
        output={"assistant_message": "Attached.", "content": [lease.model_dump(by_alias=True)]},
    )
```

## Parameters

**file\_path** `string` *required*

Path to the file on the machine running the SDK. One output accepts at most 20 files, 20 MB in total, and each must be one of these types: `pdf`, `docx`, `xlsx`, `pptx`, `rtf`, `png`, `jpg`, `jpeg`, `tiff`, `tif`, `bmp`, `webp`, `heic`, `heif`, `gif`, `txt`, `csv`, `md`, `html`, `xml`, `json`, `eml`. A storage URI is refused: there is nothing on this machine to upload, so attach it directly instead.

> [!NOTE]
>
> **A metric scores a file only when its judge model reads that kind of file.** Only a [Galtea file](https://docs.galtea.ai/v5.17/concepts/product/version/session/content-parts.md#galtea-files), one you uploaded to Galtea or one that Galtea stored from inline media, is sent to a judge. A file on your own host is stored as sent and is never sent to a judge as a file, so it never skips an evaluation: the judge reads its entry as JSON text, in its place in the turn. The kinds a judge reads depend on its model, and the model picker of the metric form shows them for each model. A judge is sent PNG, JPEG, WebP, GIF and PDF files only. The other accepted types are stored, and a Galtea input file of those types still reaches your endpoint, but no judge reads them. The rule is the same for the input and the output, and a metric that reads `conversation_turns` reads both sides of every turn. A metric that reads `traces` also reads the Galtea files of every span, and a metric that reads `retrieval_context` reads the Galtea files in the output of `RETRIEVER` spans.
>
> **Galtea numbers the files of a session.** Turn files come first, in turn order, input before output. The files of every span come next, in span start order. A file that sits in several places of a session takes one number, at its first place, and the judge receives it once. The judge reads each file in its place in the text as `[File N]`, and the session page and the span page show the same `File N` beside each Galtea file.
>
> Before an evaluation runs, Galtea checks every Galtea file on each side the metric reads. One file the judge would not read skips the evaluation, whatever text sits beside it. A skipped evaluation costs no credits, and its reason names the file with its number, its turn and what refused it:
>
> * The judge model cannot read that kind of file.
> * The model catalog does not say whether the judge model reads it.
> * The metric names no judge model.
> * The metric is DeepEval-based: those judges are sent text only.
> * The metric is deterministic: it compares text without a model.
> * The metric is a [classifier](https://docs.galtea.ai/v5.17/concepts/metric/classifier.md) metric: it is sent text only.
> * The file is a type no judge reads, such as DOCX, CSV or TIFF, or an audio file: a judge reads audio only through its transcript.
>
> When the evaluator then reads a Galtea file to send it, it skips the evaluation if the file no longer exists in storage, is empty, or is larger than the 20 MB a judge can receive. The reason names the file.
>
> Audio input with no transcript is a separate case. A metric that reads the input is skipped when no turn of the session has input text or a Galtea input file, and a turn's audio carries no transcript. Text or a Galtea file on another turn is enough, and the reason, `Evaluators read an audio input through its transcript, and no turn carries one.`, names no file.
>
> Human evaluation and self-hosted metrics are never skipped for a file or for audio. On deployments that do not send files to the judge, the evaluator also skips a metric whose judge would read the file, and the reason names the file.
>
> To have the content scored, pick a metric whose judge model reads that kind of file, or log the text your pipeline extracted as the turn input or output, without the file. See [Troubleshooting skipped evaluations](https://docs.galtea.ai/v5.17/concepts/metric/evaluation-parameters.md#troubleshooting-skipped-evaluations).

## Related Methods

* [Create Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/create.md) - Log a turn and attach files in one call
* [Update Trace](https://docs.galtea.ai/v5.17/sdk/api/trace/update.md) - Attach files to a turn you already logged
* [Upload Input File](https://docs.galtea.ai/v5.17/sdk/api/test-case/upload-input-file.md) - The same method on the input side


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