Skip to main content

Get run details

Endpoint: GET /runs/{run_id}

Description
Returns a single run you can access: yours or shared with your organization. The payload includes every evaluation and a compact representation of each record. If the id is not visible to your API key (including when the run is not assigned to the key's project), the server responds with 404 (same as “not found”).

run_type and run_source are human-readable labels (for example "Dataset", "Trace", and "API Call"), not internal enum names. user is the owning account's email, or null for org-only runs. author_email is the email of whoever created the run.

trace_id is set on trace runs and null on dataset and custom runs. The dataset field (dataset name) may be null even when the run returns 200 — for example on trace runs, or when the backing dataset exists but is not accessible to your API key (same behaviour as the dashboard “Dataset unavailable”). The run remains visible; only the nested dataset name is omitted.

permissions is computed for this caller — see Introduction — Permissions. A dataset run reports can_share, can_assign_project, and can_move_collection as false. can_edit is true when this caller may change the alias. can_delete is true when this caller owns the run, or the run is org-only and this key's owner is an organization admin using a project-scoped key.

On dataset and custom runs, each record inside evaluations is truncated to 100 characters per string field (prompt, input, context, output, golden_answer). external_id is not truncated. On trace runs, record_index and record are null (there is no dataset row). metric is the metric shortname (for example ans_corr).

Each evaluation includes optional span_id: a 16-character lowercase hex OTLP span id when that evaluation targets one span on a trace run; null for whole-trace trace evaluations and for dataset and custom runs.

Parameters

  • Path: run_id — integer run id.

Error responses

  • 401 — Authentication failed.
  • 404 — Run with id run_id not found or not accessible to your API key (including not assigned to the key's project).
  • 500 — Error retrieving the run.

Responses

  • 200 — JSON object with the shape below.

Example response (200)

{
  "id": 991,
  "user": "analyst@acme.com",
  "author_email": "analyst@acme.com",
  "run_type": "Dataset",
  "run_source": "API Call",
  "trace_id": null,
  "dataset": "Support QA - March",
  "data_collection": "Customer Support",
  "org_id": null,
  "permissions": {
    "can_edit": true,
    "can_delete": true,
    "can_share": false,
    "can_assign_project": false,
    "can_move_collection": false
  },
  "number_of_metrics": 2,
  "result": 83.5,
  "threshold": 70,
  "model_slug": "gpt-4o",
  "reasoning_level": "none",
  "alias": "support-march",
  "aggregate_results": {
    "ans_corr": 86,
    "faith": 81
  },
  "total_cost": "0.001200000000000",
  "started_at": "2026-04-01T09:12:00Z",
  "finished_at": "2026-04-01T09:13:12Z",
  "is_gte_threshold": true,
  "evaluations": [
    {
      "id": 1542,
      "run_id": 991,
      "record_index": 0,
      "span_id": null,
      "metric": "ans_corr",
      "record": {
        "id": 1001,
        "external_id": "row-42",
        "prompt": "What is 2+2?",
        "input": null,
        "context": null,
        "output": "4",
        "golden_answer": "4"
      },
      "result": 100,
      "threshold": 70,
      "explanation": "Exact match.",
      "model_slug": "gpt-4o",
      "reasoning_level": "none",
      "metric_args": null,
      "started_at": "2026-04-01T09:12:01Z",
      "finished_at": "2026-04-01T09:12:02Z",
      "evaluation_cost": "0.0004",
      "is_success": true,
      "is_gte_threshold": true,
      "eval_metadata": null
    }
  ]
}
{
  "id": 0,
  "user": "string | null",
  "author_email": "string",
  "run_type": "string",
  "run_source": "string",
  "trace_id": "integer | null",
  "dataset": "string | null",
  "data_collection": "string | null",
  "org_id": "integer | null",
  "permissions": {
    "can_edit": "boolean",
    "can_delete": "boolean",
    "can_share": "boolean",
    "can_assign_project": "boolean",
    "can_move_collection": "boolean"
  },
  "number_of_metrics": 0,
  "result": "number | null",
  "threshold": 0,
  "model_slug": "string | null",
  "reasoning_level": "string | null",
  "alias": "string | null",
  "aggregate_results": "object | null",
  "total_cost": "number | string | null",
  "started_at": "date",
  "finished_at": "date | null",
  "is_gte_threshold": "boolean | null",
  "evaluations": []
}

Each element of evaluations has this shape:

{
  "id": 0,
  "run_id": 0,
  "record_index": "integer | null",
  "span_id": "string | null",
  "metric": "string",
  "record": {
    "id": 0,
    "external_id": "string | null",
    "prompt": "string | null",
    "input": "string | null",
    "context": "string | null",
    "output": "string | null",
    "golden_answer": "string | null"
  } | null,
  "result": "number | null",
  "threshold": 0,
  "explanation": "string | null",
  "model_slug": "string | null",
  "reasoning_level": "string | null",
  "metric_args": "object | null",
  "started_at": "date",
  "finished_at": "date | null",
  "evaluation_cost": "string | null",
  "is_success": "boolean | null",
  "is_gte_threshold": "boolean | null",
  "eval_metadata": "object | null"
}

metric_args is the per-metric argument map this evaluation actually ran with. For a dataset run, that comes from the run's resolved metric set: the request's selected_metrics entry when provided, otherwise the matching entry from the dataset's default_selected_metrics. threshold on each evaluation is the effective value used for scoring (per-metric override if set, otherwise the metric catalog default). eval_metadata is a metric-specific JSON object with extra signals or null.

curl

curl "https://api.aegisevals.ai/api/v1/runs/1" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000"