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:
options
object

Execution options for launching simulations.

metadata
object

Metadata for tracking and organization purposes.

config_overrides
object | null

Launch-specific simulator configuration. Values override stored Agent configuration except for protected resource identity and connection fields. The Agent's stored model type remains authoritative.

Response

Run launched successfully

run
object
required

Minimal run resource returned immediately after launch.