Source: https://docs.cumuluslabs.io/reference/test_runs.trial
Content version: 58fabd3a

# test_runs.trial

Get one trial: its assertion trace and, while retained, the transcript it was judged on

## Request {#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 use `path`; MCP uses `params`).
- Minimum API key role: **viewer**.
- Idempotency: **none**.

Use the request schema below. Read IDs from earlier operation results.

## Input schema {#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 {#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 {#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 {#errors}

See [API error handling](https://docs.cumuluslabs.io/api#errors) and [Troubleshooting](https://docs.cumuluslabs.io/troubleshooting).

## Related guides {#related-guides}

- [Test an agent](https://docs.cumuluslabs.io/testing)
- [Build and test recipes](https://docs.cumuluslabs.io/recipes)