Skip to main content
POST
Label a trace

Authorizations

Authorization
string
header
required

Your workspace API key, e.g. sk_sovereign_..., sent as Authorization: Bearer <key>.

Body

application/json

Labels created over the API are request-scoped (one exchange). Whole-run (trace) grading is done in the dashboard's review queue.

request_id
string
required
verdict
enum<string>
required

Binary, always. Upsert by request_id: re-labeling replaces the verdict — the newest judgment is the truth.

Available options:
pass,
fail
critique
string | null

WHY, in your words (max 2000 chars). Strongly encouraged on fails: critiques become judge few-shot material, feed suggested judges, and make disagreement review meaningful.

Maximum string length: 2000

Response

The stored label.

id
string
request_id
string

The gateway request this verdict is about.

verdict
enum<string>
Available options:
pass,
fail
critique
string | null

WHY it failed — becomes judge few-shot material and the raw text 'Suggest criteria' clusters into your failure taxonomy.

source
enum<string>
Available options:
human,
assist_accepted
scope
enum<string>

request grades one exchange; trace grades a whole agent run (the label rides the run's final step). Labels created over this API are request-scoped.

Available options:
request,
trace
fail_causes
string[]

Cause attribution: criterion ids this failure indicts. Managed from the dashboard's review queue; empty on unattributed fails.

created_at
string<date-time>