Skip to main content

Create run from a dataset

Endpoint: POST /runs/dataset

Description Starts a run using an existing dataset: the server takes the dataset’s records and selected metrics.

Parameters

  • Body — application/json:
{
  "dataset_id": 1,
  "threshold": "integer | null",
  "model_slug": "string | null",
  "is_blocking": false
}

is_blocking

  • false (default)— The run and evaluation records are saved, then evaluation work is started in the background; the 201 response returns right away. Results may still be missing in that payload - poll GET /runs/{run_id} until evaluations complete. Prefer this for large datasets to avoid holding the HTTP request open.
  • true — The API waits until every evaluation for this run has been executed. The response body normally includes filled-in scores, aggregate_results, and finished_at, and credit usage for the run is finalized before you receive 201.

Error responses

  • 401, 402 — Auth or insufficient credits.
  • 422 — Body/query validation failed.
  • 404 — model_slug is not a documented model slug.
  • 400 — Dataset id not found; metric IDs from the dataset config invalid; inactive metrics; duplicate run alias (unique per user).
  • 404 — No records on the dataset; no metrics configured for the dataset.
  • 500 — Failure creating the run.

Responses

Example response (201)

{
  "id": 991,
  "user": "analyst@acme.com",
  "run_type": "Dataset",
  "run_source": "API",
  "dataset": "Support QA - March",
  "data_collection": "Customer Support",
  "number_of_metrics": 2,
  "result": 83.5,
  "threshold": 70,
  "model_slug": "gpt-4o",
  "alias": "support-march",
  "aggregate_results": {
    "ans_corr": 86,
    "faith": 81
  },
  "started_at": "2026-04-01T09:12:00Z",
  "finished_at": null,
  "is_gte_threshold": null,
  "evaluations": []
}

curl

curl -X POST "https://api.aegisevals.ai/api/v1/runs/dataset" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"dataset_id":1,"threshold":70,"model_slug":"gpt-4o","is_blocking":false}'