Skip to main content
GET
/
v1
/
simulations
List simulations
curl --request GET \
  --url https://api.coval.dev/v1/simulations \
  --header 'X-API-Key: <api-key>'
{
  "simulations": [
    {
      "name": "simulations/abc123xyz789",
      "simulation_id": "abc123xyz789",
      "run_id": "abc123xyz789",
      "status": "COMPLETED",
      "create_time": "2025-10-14T12:00:00Z",
      "has_audio": true,
      "agent_id": "gk3jK9mPq2xRt5vW8yZaBc",
      "persona_id": "hL4kL0nQr3ySt6vX9zAcDd",
      "test_set_id": "aB1cD2eF",
      "test_case_id": "test_xyz123",
      "error_message": "Simulation failed to run.",
      "mutation_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "mutation_name": "GPT-4 Fast VAD"
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOiA1MH0="
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication.

Query Parameters

​
filter
string

Filter expression syntax.

Supported fields: status, agent_id, persona_id, test_set_id, test_case_id, run_id, external_conversation_id, mutation_id, mutation_name, create_time

Operators: =, !=, >, <, >=, <=, AND, OR

Values may be unquoted or double-quoted. Values containing spaces must be quoted (e.g., status="IN PROGRESS").

The external_conversation_id field is your system's conversation ID for cross-system lookup.

Mutation Filtering: Use mutation_id or mutation_name to filter simulations by agent mutation variant. Base agent simulations have both mutation_id and mutation_name = null. To get only base agent results, filter for simulations where mutation_id is not set.

​
page_size
integer
default:50

Maximum number of results per page

Required range: 1 <= x <= 1000
​
page_token
string

Opaque pagination token from previous response

​
order_by
string
default:-create_time

Sort order specification.

Format: field or -field (descending)

Supported fields: create_time, status

Response

List of simulations

​
simulations
object[]
required

Array of simulation resources (summary view without results)

​
next_page_token
string

Token for fetching next page of results (if more exist)

Example:

"eyJvZmZzZXQiOiA1MH0="