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"
  }
}
{
  "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

​
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