On this page
test_runs.trial
Get one trial: its assertion trace and, while retained, the transcript it was judged on
Request
GET /api/v1/test-runs/{test_run_id}/cases/{case_id}/trials/{trial}
- MCP:
test_runs_trial - SDK:
client.test_runs.trial(SDK path arguments usepath; MCP usesparams). - Minimum API key role: viewer.
- Idempotency: none.
Use the request schema below. Read IDs from earlier operation results.
Input schema
json
{
"parameters": [
{
"name": "test_run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "case_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z0-9][a-z0-9_-]*$"
}
},
{
"name": "trial",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 30
}
},
{
"name": "suite_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": null
}
Responses
json
{
"200": {
"description": "Get one trial: its assertion trace and, while retained, the transcript it was judged on",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TestRunsTrialResponse200"
}
}
}
},
"4XX": {
"description": "Typed error (ApiError)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"5XX": {
"description": "Typed error (ApiError)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
Referenced schemas
json
{
"components": {
"schemas": {
"TestRunsTrialResponse200": {
"type": "object",
"properties": {
"test_run_id": {
"type": "string",
"format": "uuid"
},
"suite_id": {
"type": "string",
"format": "uuid"
},
"case_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z0-9][a-z0-9_-]*$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"result": {
"$ref": "#/components/schemas/TrialResult"
},
"case": {
"type": "object",
"properties": {
"run": {
"$ref": "#/components/schemas/Run"
},
"language": {
"type": "string",
"enum": [
"en",
"es"
]
},
"turns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0
},
"role": {
"type": "string",
"enum": [
"user",
"agent"
]
},
"text": {
"type": "string",
"maxLength": 32000
},
"node_id": {
"allOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 128
}
],
"nullable": true
},
"at_ms": {
"allOf": [
{
"type": "integer",
"minimum": 0
}
],
"nullable": true
}
},
"required": [
"index",
"role",
"text",
"node_id",
"at_ms"
],
"additionalProperties": false
},
"maxItems": 2000
},
"path": {
"type": "array",
"items": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"turn": {
"type": "integer",
"minimum": 0
},
"via": {
"type": "string",
"enum": [
"prompt_edge",
"automatic",
"action_result",
"start",
"global",
"flex_task"
]
}
},
"required": [
"node_id",
"turn",
"via"
],
"additionalProperties": false
},
"maxItems": 2000
},
"tool_calls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"effect_id": {
"type": "string",
"format": "uuid"
},
"action_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"node_id": {
"allOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 128
}
],
"nullable": true
},
"turn": {
"type": "integer",
"minimum": 0
},
"args": {},
"answered_by": {
"anyOf": [
{
"type": "object",
"properties": {
"mock": {
"type": "integer",
"minimum": 0
}
},
"required": [
"mock"
],
"additionalProperties": false
},
{
"type": "string",
"enum": [
"source_receipt"
]
},
{
"type": "string",
"enum": [
"unmocked"
]
},
{
"type": "string",
"enum": [
"default"
]
}
]
},
"state": {
"type": "string",
"enum": [
"succeeded",
"failed"
]
},
"error_code": {
"type": "string",
"maxLength": 128,
"nullable": true
}
},
"required": [
"effect_id",
"action_id",
"node_id",
"turn",
"answered_by",
"state",
"error_code"
],
"additionalProperties": false
},
"maxItems": 500
},
"transfer": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"turn": {
"type": "integer",
"minimum": 0
}
},
"required": [
"node_id",
"turn"
],
"additionalProperties": false,
"nullable": true
},
"ended": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"pattern": "^[a-z][a-z0-9_.:-]{0,127}$"
},
"class": {
"type": "string",
"enum": [
"completed",
"transferred",
"caller_hangup",
"max_turns",
"timeout",
"failed",
"cancelled",
"inactivity"
]
},
"disposition": {
"type": "string",
"maxLength": 128,
"nullable": true
},
"infrastructure": {
"type": "boolean"
}
},
"required": [
"reason",
"class",
"disposition",
"infrastructure"
],
"additionalProperties": false
},
"variables": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 4096
}
},
"guard_events": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"compliance_block"
]
},
"turn": {
"type": "integer",
"minimum": 0
},
"rule": {
"type": "string",
"pattern": "^[a-z][a-z0-9_.:-]{0,127}$"
},
"clause_hash": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"type",
"turn",
"rule",
"clause_hash"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"rpc_unconfirmed"
]
},
"turn": {
"type": "integer",
"minimum": 0
}
},
"required": [
"type",
"turn"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"atomic_unit"
]
},
"turn": {
"type": "integer",
"minimum": 0
},
"unit_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"delivered": {
"type": "boolean"
}
},
"required": [
"type",
"turn",
"unit_id",
"delivered"
],
"additionalProperties": false
}
]
},
"maxItems": 2000
},
"caller_trace": {
"type": "object",
"properties": {
"clock": {
"type": "string",
"enum": [
"participant"
]
},
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"step": {
"type": "integer",
"nullable": true
},
"start": {
"type": "number"
},
"end": {
"type": "number"
},
"pauses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "number"
},
"end": {
"type": "number"
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
},
"maxItems": 10
},
"kind": {
"type": "string",
"enum": [
"line",
"interjection",
"backchannel",
"beep"
]
}
},
"required": [
"step",
"start",
"end",
"pauses",
"kind"
],
"additionalProperties": false
},
"maxItems": 200
},
"agent_audio": {
"type": "array",
"items": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": [
{
"type": "number"
},
{
"type": "number"
}
]
},
"maxItems": 2000
},
"joined_at_unix_ms": {
"type": "integer",
"minimum": 0,
"nullable": true,
"default": null
}
},
"required": [
"clock",
"lines",
"agent_audio"
],
"additionalProperties": false,
"nullable": true
},
"redaction": {
"type": "object",
"properties": {
"policy_version": {
"type": "string",
"minLength": 1
}
},
"required": [
"policy_version"
],
"additionalProperties": false,
"nullable": true
},
"cost_usd": {
"type": "number",
"minimum": 0,
"nullable": true
}
},
"required": [
"run",
"language",
"turns",
"path",
"tool_calls",
"transfer",
"ended",
"variables",
"guard_events",
"caller_trace",
"redaction",
"cost_usd"
],
"additionalProperties": false,
"nullable": true
}
},
"required": [
"test_run_id",
"suite_id",
"case_id",
"name",
"result",
"case"
],
"additionalProperties": false
},
"TrialResult": {
"type": "object",
"properties": {
"case_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z0-9][a-z0-9_-]*$"
},
"trial": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
},
"attempt": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
},
"run_id": {
"allOf": [
{
"type": "string",
"format": "uuid"
}
],
"nullable": true
},
"state": {
"type": "string",
"enum": [
"pending",
"running",
"evaluating",
"settled",
"cancelled"
]
},
"verdict": {
"type": "string",
"enum": [
"passed",
"failed",
"errored"
],
"nullable": true
},
"reason": {
"allOf": [
{
"type": "string",
"pattern": "^[a-z][a-z0-9_.:-]{0,127}$"
}
],
"nullable": true
},
"assertions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"assertion_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$"
},
"type": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"verdict": {
"type": "string",
"enum": [
"passed",
"failed",
"not_applicable",
"insufficient_data",
"errored"
]
},
"measured": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "number"
},
{
"type": "boolean"
}
],
"nullable": true
}
},
"evidence": {
"type": "object",
"properties": {
"turns": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0
},
"maxItems": 50
},
"node_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"maxItems": 50
},
"effect_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20
}
},
"required": [
"turns",
"node_ids",
"effect_ids"
],
"additionalProperties": false
},
"judge": {
"type": "object",
"properties": {
"score": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"rejudged": {
"type": "boolean"
},
"criteria": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"verdict": {
"type": "string",
"enum": [
"pass",
"fail",
"na"
]
},
"score": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"nullable": true
},
"evidence_turns": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0
},
"maxItems": 20
},
"rationale": {
"type": "string",
"maxLength": 300,
"nullable": true
}
},
"required": [
"id",
"verdict",
"score",
"evidence_turns",
"rationale"
],
"additionalProperties": false
},
"maxItems": 12
}
},
"required": [
"score",
"rejudged",
"criteria"
],
"additionalProperties": false,
"nullable": true
},
"reason": {
"allOf": [
{
"type": "string",
"pattern": "^[a-z][a-z0-9_.:-]{0,127}$"
}
],
"nullable": true
}
},
"required": [
"assertion_id",
"type",
"verdict",
"measured",
"evidence",
"judge",
"reason"
],
"additionalProperties": false
},
"maxItems": 25
},
"guard": {
"type": "object",
"properties": {
"compliance_blocks": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0
}
},
"rpc_unconfirmed": {
"type": "integer",
"minimum": 0
},
"atomic_half_said": {
"type": "integer",
"minimum": 0
}
},
"required": [
"compliance_blocks",
"rpc_unconfirmed",
"atomic_half_said"
],
"additionalProperties": false
},
"content_state": {
"type": "string",
"enum": [
"retained",
"expired"
]
}
},
"required": [
"case_id",
"trial",
"attempt",
"run_id",
"state",
"verdict",
"reason",
"assertions",
"guard",
"content_state"
],
"additionalProperties": false
},
"Run": {
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"tenant_id": {
"type": "string",
"format": "uuid"
},
"run_id": {
"type": "string",
"format": "uuid"
},
"agent_id": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
},
"publication": {
"$ref": "#/components/schemas/PublicationRef"
},
"plan_schema_version": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
},
"channel": {
"type": "string",
"enum": [
"cloud",
"phone",
"web"
]
},
"mode": {
"type": "string",
"enum": [
"task",
"chat",
"background",
"outbound",
"inbound"
]
},
"state": {
"type": "string",
"enum": [
"admitted",
"running",
"ending",
"completed",
"failed",
"cancelled",
"rejected",
"expired"
]
},
"phone_state": {
"type": "string",
"enum": [
"admitted",
"preparing",
"awaiting_sip",
"dialing",
"ringing",
"active",
"terminating",
"ended",
"rejected",
"expired",
"setup_failed"
],
"nullable": true
},
"outcome": {
"allOf": [
{
"$ref": "#/components/schemas/RunOutcome"
}
],
"nullable": true
},
"disposition": {
"type": "string",
"nullable": true
},
"trigger": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"sip"
]
},
"number_id": {
"type": "string",
"format": "uuid"
},
"call_id_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"kind",
"number_id",
"call_id_sha256"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"api"
]
},
"idempotency_key_sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"kind",
"idempotency_key_sha256"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"schedule"
]
},
"trigger_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"scheduled_for": {
"type": "string",
"format": "date-time"
}
},
"required": [
"kind",
"trigger_id",
"scheduled_for"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"event"
]
},
"trigger_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"source_event_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"kind",
"trigger_id",
"source_event_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"callback"
]
},
"source_run_id": {
"type": "string",
"format": "uuid"
},
"effect_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"kind",
"source_run_id",
"effect_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"evaluation"
]
},
"comparison_id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"kind",
"comparison_id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"test"
]
},
"test_run_id": {
"type": "string",
"format": "uuid"
},
"suite_id": {
"type": "string",
"format": "uuid"
},
"case_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z0-9][a-z0-9_-]*$"
},
"trial": {
"type": "integer",
"exclusiveMinimum": true,
"minimum": 0
}
},
"required": [
"kind",
"test_run_id",
"suite_id",
"case_id",
"trial"
],
"additionalProperties": false
}
]
},
"principal": {
"$ref": "#/components/schemas/PrincipalRef"
},
"attempt_count": {
"type": "integer",
"minimum": 0
},
"created_at": {
"type": "string",
"format": "date-time"
},
"started_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"ended_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"to": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"nullable": true
},
"from": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"nullable": true
},
"duration_ms": {
"type": "integer",
"minimum": 0,
"nullable": true
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"test": {
"type": "boolean"
},
"provider_keys": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"platform"
]
}
},
"required": [
"source"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"tenant"
]
},
"last4": {
"type": "string",
"minLength": 1,
"maxLength": 4
},
"fingerprint": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{12}$"
}
},
"required": [
"source",
"last4",
"fingerprint"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"owner_id",
"environment",
"tenant_id",
"run_id",
"agent_id",
"publication",
"plan_schema_version",
"channel",
"mode",
"state",
"phone_state",
"outcome",
"disposition",
"trigger",
"principal",
"attempt_count",
"created_at",
"started_at",
"ended_at",
"version",
"to",
"from",
"duration_ms",
"metadata",
"test"
],
"additionalProperties": false
},
"PublicationRef": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
},
"version": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"digest": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
}
},
"required": [
"agent_id",
"version",
"digest"
],
"additionalProperties": false
},
"RunOutcome": {
"type": "object",
"properties": {
"transport": {
"type": "string",
"enum": [
"completed",
"busy",
"no_answer",
"rejected",
"cancelled",
"provider_failure",
"admission_expired",
"not_applicable"
]
},
"execution": {
"type": "string",
"enum": [
"completed",
"failed",
"cancelled",
"not_started",
"unknown"
]
},
"contact": {
"type": "string",
"enum": [
"human",
"voicemail",
"ivr",
"unknown",
"not_applicable"
]
},
"business": {
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"known"
]
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"status",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"unknown"
]
}
},
"required": [
"status"
],
"additionalProperties": false
}
]
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"result": {
"allOf": [
{
"$ref": "#/components/schemas/ContentRef"
}
],
"nullable": true
}
},
"required": [
"transport",
"execution",
"contact",
"business",
"reason",
"result"
],
"additionalProperties": false
},
"ContentRef": {
"type": "object",
"properties": {
"artifact_id": {
"type": "string",
"format": "uuid"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"byte_size": {
"type": "integer",
"minimum": 0
},
"media_type": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"artifact_id",
"sha256",
"byte_size",
"media_type",
"expires_at"
],
"additionalProperties": false
},
"PrincipalRef": {
"anyOf": [
{
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"user"
]
},
"id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"owner_id",
"environment",
"kind",
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"api_key"
]
},
"id": {
"type": "string",
"format": "uuid"
}
},
"required": [
"owner_id",
"environment",
"kind",
"id"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"owner_id": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"minLength": 1
},
"kind": {
"type": "string",
"enum": [
"system"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": [
"owner_id",
"environment",
"kind",
"id"
],
"additionalProperties": false
}
]
},
"ApiError": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"unauthenticated",
"forbidden",
"not_found",
"conflict",
"invalid_request",
"idempotency_conflict",
"policy_denied",
"capability_unavailable",
"provider_unavailable",
"knowledge_unavailable",
"publication_invalid",
"run_not_active",
"rate_limited",
"outcome_unknown",
"internal"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"outcome": {
"type": "string",
"enum": [
"none",
"unknown"
]
},
"details": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"code",
"message",
"retryable",
"outcome"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
Errors and recovery
See API error handling and Troubleshooting.
Related guides
Content version 58fabd3aMarkdown source