List Evaluations

import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
headers = {
    "Authorization": f"Bearer {API_KEY}",
}
response = requests.get(
    f"{BASE_URL}/v3/evals",
    headers=headers,
    params={
        "limit": 25,
    },
    timeout=30.0
)
if response.status_code == 200:
    data = response.json()
    for ev in data["evals"]:
        best = max(
            (c for c in ev["scorecards"].values() if c.get("recall_at_10") is not None),
            key=lambda c: c["recall_at_10"],
            default=None,
        )
        found = f"{best['recall_at_10']:.0%} found" if best else f"{ev['progress']['percent']}% complete"
        print(f"{ev['eval_id']}  {ev['status']:22s} {ev['collection_name']:20s} {found}")
    # Page until next_cursor is null
    print(f"next_cursor={data['next_cursor']}")
else:
    print(f"Error: {response.status_code}")

{
  "count": 2,
  "evals": [
    {
      "cases": 3,
      "cases_error": 1,
      "collection_name": "customer_forms",
      "created_at": "2026-09-12T14:02:11.418Z",
      "eval_id": "eval_019b4c2f11d04c8e9a7b3d5c2e1840ff",
      "progress": {
        "cases_error": 1,
        "cases_total": 3,
        "configs_failed": 0,
        "configs_total": 3,
        "elapsed_seconds": 9,
        "percent": 100,
        "units_completed": 6,
        "units_error": 3,
        "units_failed": 0,
        "units_total": 9,
        "eta_seconds": 0,
        "qps": 2
      },
      "status": "completed_with_errors",
      "units": 9,
      "updated_at": "2026-09-12T14:02:22.640Z",
      "billing": {
        "billable_units": 6,
        "skipped_units": 3,
        "failed_configs": []
      },
      "completed_at": "2026-09-12T14:02:22.640Z",
      "config_names": [
        "baseline",
        "rerank",
        "rerank-deep"
      ],
      "environment": "development",
      "error_code": null,
      "scorecards": {
        "baseline": {
          "error": 1,
          "failed": 0,
          "question_set_size": 3,
          "scored": 2,
          "status": "scored",
          "latency_p50_ms": 412,
          "latency_p95_ms": 690,
          "mrr": 0.75,
          "ndcg_at_10": 0.88,
          "recall_at_1": 0.5,
          "recall_at_10": 1,
          "recall_at_3": 1
        }
      },
      "started_at": "2026-09-12T14:02:13.902Z"
    },
    {
      "cases": 500,
      "cases_error": 0,
      "collection_name": "customer_forms",
      "created_at": "2026-09-12T13:55:40.117Z",
      "eval_id": "eval_019b3a81c4e2748fb0d95e17c3aa62b1",
      "progress": {
        "cases_error": 0,
        "cases_total": 500,
        "configs_failed": 0,
        "configs_total": 2,
        "elapsed_seconds": 185,
        "percent": 41,
        "units_completed": 410,
        "units_error": 0,
        "units_failed": 0,
        "units_total": 1000,
        "eta_seconds": 260,
        "qps": 2.1
      },
      "status": "running",
      "units": 1000,
      "updated_at": "2026-09-12T13:58:46.220Z",
      "billing": null,
      "completed_at": null,
      "config_names": [
        "baseline",
        "rerank"
      ],
      "environment": "development",
      "error_code": null,
      "scorecards": {},
      "started_at": "2026-09-12T13:55:41.002Z"
    }
  ],
  "next_cursor": null
}

List your evaluations, newest first, scoped to the environment of the API key you call with.

Each row carries the status, progress and per-configuration scorecards, so a dashboard or agent can show where every evaluation stands without fetching each one. Per-case results and stored answers stay on GET /v3/evals/{eval_id}.

Page with cursor until next_cursor is null; there is no total count. Evaluations still running are settled against their job before the page returns, up to a few per page, so a finished run stops reading as running.

Query parameters

collectionstring or nullOptional

Only evaluations against this collection.

statusstring or nullOptional

Filter by status: pending, running, completed, completed_with_errors or failed.

limitintegerOptional1-100Defaults to 25

Rows per page (1-100).

cursorstring or nullOptional<=512 characters

Continue from a previous page’s next_cursor.

Response

Successful Response

countinteger

Rows on this page. There is no total; page until next_cursor is null.

evalslist of objectsOptional

next_cursorstring or nullOptional

Pass as cursor to continue. Null on the last page.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

422

Unprocessable Entity Error