Skip to main content
GET
/
runs
List runs
curl --request GET \
  --url https://api.coval.dev/v1/runs \
  --header 'X-API-Key: <api-key>'
{
  "runs": [
    {
      "name": "runs/abc123xyz789",
      "run_id": "8EktrIgaVxn9LfxkIynagX",
      "status": "COMPLETED",
      "create_time": "2025-10-14T12:00:00Z",
      "update_time": "2025-10-14T12:15:00Z",
      "agent_id": "gk3jK9mPq2xRt5vW8yZaBc",
      "persona_id": "hL4kL0nQr3ySt6vX9zAcDd",
      "test_set_id": "aB1cD2eF",
      "tags": [
        "regression",
        "v2.1"
      ],
      "progress": {
        "total_test_cases": 10,
        "completed_test_cases": 8,
        "failed_test_cases": 1,
        "in_progress_test_cases": 1
      },
      "results": {
        "output_ids": [
          "sim_output_abc123",
          "sim_output_def456"
        ],
        "metrics": {
          "availability": {
            "mean": 0.95,
            "min": 0.85,
            "max": 1
          }
        }
      },
      "metadata": {
        "campaign_id": "q4_2025",
        "environment": "production"
      },
      "error": "Agent connection timeout"
    }
  ],
  "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, create_time, update_time, created_by, tag

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

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

​
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, update_time, status, agent_id, persona_id, test_set_id

Response

List of runs

​
runs
object[]
required
​
next_page_token
string

Token for fetching the next page of results

Example:

"eyJvZmZzZXQiOiA1MH0="