Skip to main content
This page covers the small set of concepts you need to integrate Tuor cleanly: traces, review outcomes, payload shapes, and how reviewed data gets back to your system.

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 as pending. 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 and malformed spans are preserved as 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

Outputs model_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.