Trace
A trace is one ordered model trajectory that can be reviewed by a human. It has three payloads you control:
Tuor adds review fields:
Each JSON payload field is capped at 5 MB and 10 nesting levels.
Review outcomes
Every trace starts aspending. Reviewers then choose one of three outcomes:
For most integrations, this is the state machine that matters: send traces while they are
pending, then consume approved and corrected traces through webhooks or export.
Span taxonomy
spans is a flat array. Its order is the trace order; Tuor does not sort, group, or infer model-call boundaries. Every returned span receives a Tuor-generated id.
Keep provider-specific error details in an error span’s content, and tool failures in the tool response.
Every span supports ordered
text, json, encrypted, refusal, image, and document blocks. Media blocks describe their base64 source; an image may instead give a url source, which Tuor shows as a link and never fetches. A document looks like:
unknown spans. Unknown or malformed content becomes a json block at the smallest valid boundary. Tool requests and responses may be orphaned, duplicated, ambiguous, or out of order; Tuor renders the supplied trajectory without inventing status.
Tuor calls these ordered units spans, but they are not full OpenTelemetry spans and are not OTLP-compatible.
Output shapes
Outputsmodel_output is structured JSON — the reviewer edits nested object leaves as dot-path form rows. Values can be strings, numbers, booleans, arrays, or nested objects. Each form row gets a sensible control inferred from the value’s type, but you can pin a path to a specific typed control by describing its dot path in the trace’s output_schema. Three field types are available:
Paths absent from
output_schema are unconstrained JSON and fall back to inferred controls. For enum fields, add "multi": true for multi-label fields and "open": false to reject write-in values at ingest and correction time; boolean rejects non-boolean values, and json accepts any JSON. See Reviewer Blueprints for practical recipes.
Getting results back
There are three common patterns:
Use
trace_config aggressively. For example, include internal_run_id, prompt_version_id, and customer_id when you create a trace. Tuor echoes those values in exports and on the trace object returned by GET /v1/traces/{trace_id}, so most downstream systems do not need a separate mapping table.