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

# Uploading traces

> Upload supported traces with the Python SDK or Prime CLI

## Automatic and explicit uploads

Online runs using the Prime Runs SDK upload traces to Prime Traces by default when the account has access. Run metadata and training metrics still use the Platform API. Local files are separate: writing a `traces.jsonl` file to disk does not itself upload it.

For local evaluations, follow the upload instructions for the producer and format you are using. Legacy `vf-eval` results and `prime eval push` workflows are distinct from directly uploading verifiers v1 traces. See [legacy storage retirement](/traces/legacy-storage).

Uploads are subject to [ingestion and storage charges](/traces/pricing-and-settings). To control automatic run uploads, see [upload settings](/traces/pricing-and-settings#control-run-uploads).

## Authentication and workspace

1. Create an [API key](/api-reference/api-keys) with **Prime Traces** read and/or write permissions (`traces:read`, `traces:write`) for the operations you need.
2. Authenticate with `prime login` or set `PRIME_API_KEY`.
3. Select the intended workspace. Set `PRIME_TEAM_ID` for team data; the SDK also reads the team from your CLI configuration. Check `prime config view` before uploading.

```bash theme={null}
prime login
prime config view
export PRIME_TEAM_ID="your-team-id"
```

To return to personal context, remove a shell override with `unset PRIME_TEAM_ID` and clear a configured team with `prime config remove-team-id`. The destination workspace owns the uploaded data and its usage.

## Supported records

Prime Traces currently supports **verifiers v1 traces and episodes**. A JSONL extension describes the file container, not its schema. Preserve the producer's records rather than converting legacy `prompt` / `completion` / `reward` rows by renaming fields.

The [SDK upload example](https://github.com/PrimeIntellect-ai/prime/blob/v0.9.4/packages/prime-traces/examples/basic_usage.py) includes a small service-compatible record and validation handling. It is a reduced example, not the complete verifiers schema. For actual runs, use the trace or episode objects emitted by verifiers, or their serialized output.

Trace records require a non-empty `id` and numeric `timing.start`; other validation rules also apply. Passing those two checks alone does not establish that a legacy record is a complete verifiers trace. The [upload API reference](/api-reference/traces/ingestion/upload-traces) describes the request and validation errors.

## Python SDK

```bash theme={null}
uv add prime-traces
```

The SDK accepts producer objects exposing `to_record()` as well as serialized records:

```python theme={null}
from prime_traces import LineFormat, TracesClient

# `traces` and `episodes` are objects emitted by your verifiers run.
with TracesClient() as client:
    receipts = client.upload_records(traces, context={"source": "my-eval"})

    # For episode records, select the episode line format explicitly.
    episode_receipts = client.upload_records(
        episodes, line_format=LineFormat.EPISODE
    )
```

For a JSONL file you have prepared with one supported trace record per line (called `trace-records.jsonl` in this example):

```python theme={null}
from prime_traces import TracesClient

with TracesClient() as client:
    receipts = client.upload_file("trace-records.jsonl", context={"source": "my-eval"})
```

Verifiers v1 (`vf`) saves completed rollout **episodes** in `traces.jsonl`, with each episode containing its traces. For this file, select `LineFormat.EPISODE` explicitly:

```python theme={null}
from prime_traces import LineFormat, TracesClient

with TracesClient() as client:
    receipts = client.upload_file(
        "traces.jsonl", line_format=LineFormat.EPISODE
    )
```

prime-rl (`prl`) also saves rollout episodes through its file monitor; the output paths and chunking depend on the version and configuration. Use episode format for completed episode records, not for metrics, indexes, or live trace-delta files. See the [Verifiers episode writer](https://github.com/PrimeIntellect-ai/verifiers/blob/main/verifiers/v1/utils/trace_store.py) and [prime-rl file monitor](https://github.com/PrimeIntellect-ai/prime-rl/blob/main/src/prime_rl/monitors/file/monitor.py).

Choose the line format from the records in the file, not its filename.

## CLI

For a file containing one supported trace record per line:

```bash theme={null}
prime traces upload trace-records.jsonl
```

Use `prime traces upload --help` to inspect the options in your installed version, including line format. See [CLI installation](/cli-reference/introduction) to update the CLI.

## Verify the upload

Open the [Traces dashboard](https://app.primeintellect.ai/dashboard/traces) in the same workspace, or query the run ID recorded in the uploaded data:

```bash theme={null}
prime traces list --run-id your-run-id
```

A validation error means the input needs correcting; retrying an unchanged file will not fix it. For permissions, workspace, and quota problems, see [troubleshooting](/traces/managing-traces#troubleshooting).


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