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"
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Request validation failed",
"details": [
{
"field": "iteration_count",
"description": "Value must be between 1 and 10"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Invalid or missing API key",
"details": [
{
"field": "X-API-Key",
"description": "API key is required in the X-API-Key header"
}
]
}
}{
"error": {
"code": "PERMISSION_DENIED",
"message": "Access denied",
"details": [
{
"description": "Your organization does not have access to this resource"
}
]
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Run not found",
"details": [
{
"field": "run_id",
"description": "Run 'abc123xyz789' does not exist or is not accessible by your organization"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred. Please contact support."
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Service temporarily unavailable",
"details": [
{
"description": "Database routing is temporarily unavailable. Please retry."
}
]
}
}Launch run
Launch a new simulation run to evaluate an agent against test cases using a persona.
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"
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Request validation failed",
"details": [
{
"field": "iteration_count",
"description": "Value must be between 1 and 10"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Invalid or missing API key",
"details": [
{
"field": "X-API-Key",
"description": "API key is required in the X-API-Key header"
}
]
}
}{
"error": {
"code": "PERMISSION_DENIED",
"message": "Access denied",
"details": [
{
"description": "Your organization does not have access to this resource"
}
]
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Run not found",
"details": [
{
"field": "run_id",
"description": "Run 'abc123xyz789' does not exist or is not accessible by your organization"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred. Please contact support."
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Service temporarily unavailable",
"details": [
{
"description": "Database routing is temporarily unavailable. Please retry."
}
]
}
}Authorizations
API key for authentication
Body
The agent to test. Must be owned by the authenticated organization.
22"gk3jK9mPq2xRt5vW8yZaBc"
The simulated persona to use for testing.
22"hL4kL0nQr3ySt6vX9zAcDd"
The test set containing test cases to run.
8"aB1cD2eF"
Optional list of metric IDs to evaluate. If not provided, uses agent's default metrics.
22[
"iM5lM1oRs4zTu7wY0aBdEe",
"jN6mN2pSt5aUv8xZ1bCeFf"
]
Single mutation ID to run in addition to the base agent.
Mutually exclusive with mutation_ids. The base agent always runs.
26"01ARZ3NDEKTSV4RRFFQ69G5FAV"
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))
10026[
"01ARZ3NDEKTSV4RRFFQ69G5FAV",
"01ARZ3NDEKTSV4RRFFQ69G5FAW"
]
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').
["latency", "interruption_rate"]
Execution options for launching simulations.
Show child attributes
Show child attributes
Metadata for tracking and organization purposes.
Show child attributes
Show child attributes
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
Show child attributes
Show child attributes
Was this page helpful?