Uploading traces

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. Uploads are subject to ingestion and storage charges. To control automatic run uploads, see upload settings.

Authentication and workspace

Create an API key with Prime Traces read and/or write permissions (traces:read, traces:write) for the operations you need.
Authenticate with prime login or set PRIME_API_KEY.
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.

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 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 describes the request and validation errors.

Python SDK

uv add prime-traces

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

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):

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:

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 and prime-rl file monitor. Choose the line format from the records in the file, not its filename.

CLI

For a file containing one supported trace record per line:

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 to update the CLI.

Verify the upload

Open the Traces dashboard in the same workspace, or query the run ID recorded in the uploaded data:

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.

Getting Started

Lab

Inference

Model Factory

Libraries

Compute

Automatic and explicit uploads

Authentication and workspace

Supported records

Python SDK

CLI

Verify the upload

​Automatic and explicit uploads

​Authentication and workspace

​Supported records

​Python SDK

​CLI

​Verify the upload

Automatic and explicit uploads

Authentication and workspace

Supported records

Python SDK

CLI

Verify the upload