Skip to main content

Upload Ground Truth

POST 
/traces/versions/:version_id/ground-truth

Attach customer-supplied ground truth to a landed trace version, deriving a new version (201).

The file maps each session/trace identifier to its ground-truth columns (e.g. expected_tools for tool_selection_accuracy). Identifiers are validated against the version's own session keys, so a file keyed against the wrong dataset is rejected rather than stored and never read.

The base version is never mutated: the response's dataset_version_id is a new version. Partitions/eval targets already defined against the base are carried onto it — the spans are the same object, so the same selector resolves to the same scope — and migrated_partitions reports what happened to each, including any that could not move. The base keeps its own copies; versions are immutable. Uploading against a version that already carries ground truth merges over it, column by column; re-submitting a byte-identical file returns the version already derived from it (replayed: true) rather than a duplicate.

Replay is keyed on the base, not on content alone: a retry gets replayed: true only when it re-submits against the same version_id as the original attempt. Uploading the same file against the version it just derived is a different request — the merge is a no-op, but it still derives a new, indistinguishable version — so a client that always uploads against "the dataset's latest version" accumulates one no-op per retry. Pin the base for retries, and treat the returned dataset_version_id as the result to record rather than as the next upload target. Keyed this way because a derived version inherits its base's spans (minio_path): two bases with different span sets can yield byte-identical ground truth, and replaying across them would hand back a version scoped to the wrong spans.

Returns 404 if the version does not exist or belongs to a workspace the caller is not a member of, and 403 if the caller is a member without editor-level access. Returns 422 if the file is oversized, is not valid CSV/JSON/JSONL, or names identifiers the base version does not recognize. Returns 500 in the rare case where the newly derived version's metadata does not record the artifact path it was just written to.

Request​

Responses​

Successful Response