Skip to main content
POST

Authorizations

X-API-Key
string
header
required

API key for authentication

Body

application/json
agent_id
string
required

The agent to test. Must be owned by the authenticated organization.

Required string length: 22
Example:

"gk3jK9mPq2xRt5vW8yZaBc"

persona_id
string
required

The simulated persona to use for testing.

Required string length: 22
Example:

"hL4kL0nQr3ySt6vX9zAcDd"

test_set_id
string
required

The test set containing test cases to run.

Required string length: 8
Example:

"aB1cD2eF"

metric_ids
string[]

Optional list of metric IDs to evaluate. If not provided, uses agent's default metrics.

Required string length: 22
Example:
mutation_id
string | null

Single mutation ID to run in addition to the base agent. Mutually exclusive with mutation_ids. The base agent always runs.

Required string length: 26
Example:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

mutation_ids
string[]

List of mutation IDs to run in addition to the base agent. Mutually exclusive with mutation_id. Max 100 mutations. The base agent always runs alongside all mutations.

Total simulations = test_cases × iterations × (1 + len(mutation_ids))

Maximum array length: 100
Required string length: 26
Example:
persona_metrics
string[]

List of metric names that should evaluate the persona instead of the agent. Each entry should be the base metric name (e.g., 'latency', not 'persona:latency').

Example:
options
object

Execution options for launching simulations.

metadata
object

Metadata for tracking and organization purposes.

Response

Run launched successfully

run
object
required