Skip to main content
POST
/
runs
curl --request POST \ --url https://api.coval.dev/v1/runs \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --data ' { "agent_id": "gk3jK9mPq2xRt5vW8yZaBc", "persona_id": "hL4kL0nQr3ySt6vX9zAcDd", "test_set_id": "aB1cD2eF" } '
{
  "run": {
    "name": "runs/3zfmuDbVQsi4GaseDtiVcS",
    "run_id": "3zfmuDbVQsi4GaseDtiVcS",
    "status": "PENDING",
    "create_time": "2025-10-14T12:00:00Z"
  }
}

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:
[
  "iM5lM1oRs4zTu7wY0aBdEe",
  "jN6mN2pSt5aUv8xZ1bCeFf"
]
​
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:
[
  "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "01ARZ3NDEKTSV4RRFFQ69G5FAW"
]
​
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:
["latency", "interruption_rate"]
​
options
object

Execution options for launching simulations.

​
metadata
object

Metadata for tracking and organization purposes.

Response

Run launched successfully

​
run
object
required