Get datasets

This page documents read endpoints for datasets:

Partial list (summary fields per dataset): GET /datasets/all-partial — custom only
Paginated list: GET /datasets — defaults to custom; pass dataset_type_id for proprietary or other types
One dataset by id: GET /datasets/{dataset_id} — custom or proprietary when accessible

Get datasets (partial)

Endpoint: GET /datasets/all-partial

Description

Returns a lightweight list of your non-proprietary datasets, newest first. Each element has: id, name, description, user, org_id, project_id, author_email, created_at, and updated_at (not full rows, metrics, or records). With a project-scoped API key, only datasets assigned to that project are returned — see Introduction — API key scoping.

Parameters

shared — optional boolean. false returns only your own datasets; true returns only datasets shared with you; omit to return all you can access.

Error responses

401 — Authentication failed.
404 — shared=true without organization scope (solo account or private API key).
500 — Server error.

Responses

200 — JSON array of partial dataset objects with the fields listed above (not the full get-by-id shape).

Example response (200)

[
  {
    "id": 3,
    "name": "support_qa_march.csv",
    "description": "March support QA prompts",
    "user": { "id": 7, "email": "analyst@acme.com" },
    "org_id": null,
    "project_id": null,
    "author_email": "analyst@acme.com",
    "created_at": "2026-03-30T10:00:00Z",
    "updated_at": null
  }
]

curl

curl "https://api.aegisevals.ai/api/v1/datasets/all-partial" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000"

Get all datasets (paginated)

Endpoint: GET /datasets

Description

Returns a paginated list of dataset summaries. If you omit dataset_type_id, results are limited to the CUSTOM type (user-created datasets), not every dataset type. Pass a type id explicitly to list proprietary or other types your account may access. With a project-scoped API key, only datasets assigned to that project are returned — see Introduction — API key scoping.

Parameters

page — integer, default 1, minimum 1.
page_size — integer, default 10, between 1 and 10000.
dataset_type_id — optional integer. When set, only datasets with that type id are returned. When omitted, behavior matches filtering to the CUSTOM type id (same query shape as passing that id). Valid ids are returned by GET /dataset-types.
shared — optional boolean. false returns only your own datasets; true returns only datasets shared with you; omit to return all you can access.
search — optional string (max 255 characters). Case-insensitive substring match on dataset name; if the value is all digits, also matches dataset id exactly.
metric_shortnames — optional comma-separated list of metric shortnames (for example ans_corr,faith). Returns datasets whose selected_metrics includes at least one of the listed metrics.
data_collection_ids — optional comma-separated list of positive integers (for example 14,22). Returns datasets whose data_collection_id is one of the listed ids. Invalid tokens (non-integers, zero, or negative values) yield 422.

Error responses

401, 422 — Auth, invalid page / page_size, or invalid data_collection_ids.
404 — Referenced dataset type not found (when dataset_type_id is set); or shared=true without organization scope (solo account or private API key).
500 — Server error.

Responses

200 — JSON with items and meta:

Example response (200)

{
  "items": [
    {
      "id": 3,
      "user": { "id": 7, "email": "analyst@acme.com" },
      "dataset_type_id": 1,
      "name": "support_qa_march.csv",
      "description": "March support QA prompts",
      "selected_metrics": {
        "1": { "threshold": 70, "metric_args": null },
        "2": { "threshold": 80, "metric_args": null }
      },
      "structure": ["external_id", "prompt", "output", "golden_answer"],
      "column_mappings": {
        "external_id": "row_id",
        "prompt": "question",
        "output": "model_answer",
        "golden_answer": "expected_answer"
      },
      "data_collection_id": 14,
      "org_id": null,
      "project_id": null,
      "author_email": "analyst@acme.com",
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": null
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_items": 1,
    "items_on_page": 1,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "next_page": null,
    "previous_page": null
  }
}

{
  "items": [
    {
      "id": 0,
      "user": { "id": 0, "email": "string" },
      "dataset_type_id": 0,
      "name": "string",
      "description": "string | null",
      "selected_metrics": "object | null",
      "structure": ["string"],
      "column_mappings": "object | null",
      "data_collection_id": "integer | null",
      "org_id": "integer | null",
      "project_id": "integer | null",
      "author_email": "string",
      "created_at": "date",
      "updated_at": "date | null"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 10,
    "total_items": 1,
    "items_on_page": 1,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false,
    "next_page": "integer | null",
    "previous_page": "integer | null"
  }
}

curl

curl "https://api.aegisevals.ai/api/v1/datasets?page=1&page_size=20" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000"

With filters:

curl "https://api.aegisevals.ai/api/v1/datasets?page=1&page_size=20&search=support&metric_shortnames=ans_corr&data_collection_ids=14" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000"

Get dataset by id

Endpoint: GET /datasets/{dataset_id}

Description

Returns one dataset with dataset type, records, runs (your runs on this dataset), evaluations, and last_run_id. Evaluations are scoped to the most recent run that matches the API dataset run source and dataset run type (when such a run exists); otherwise the evaluations array may be empty even if older runs exist. last_run_id is that same most-recent API dataset run’s id, or null when none exists. Proprietary datasets are returned when accessible (see Datasets).

Parameters

Path: dataset_id — integer.

Error responses

401 — Authentication failed.
404 — Dataset not found or not accessible to your API key (including unassigned, assigned to a different project, or otherwise outside the key's project scope).
500 — Server error.

Responses

200 — JSON with the full dataset object; see Example response (200) and field shapes below.

Example response (200)

{
  "id": 42,
  "user": { "id": 7, "email": "analyst@acme.com" },
  "dataset_type_id": 1,
  "name": "My evaluation set",
  "description": "Evaluation prompts for support QA",
  "selected_metrics": {
    "1": { "threshold": 70, "metric_args": null },
    "2": { "threshold": 80, "metric_args": { "ignore_extra_keys": true } }
  },
  "structure": ["external_id", "prompt", "output", "golden_answer"],
  "column_mappings": {
    "external_id": "row_id",
    "prompt": "question",
    "output": "model_answer",
    "golden_answer": "expected_answer"
  },
  "data_collection_id": null,
  "org_id": null,
  "project_id": null,
  "author_email": "analyst@acme.com",
  "created_at": "2026-04-02T12:00:00Z",
  "updated_at": null,
  "dataset_type": {
    "id": 1,
    "name": "CUSTOM",
    "label": "Custom",
    "description": null
  },
  "records": [
    {
      "id": 1001,
      "user_id": 7,
      "dataset_id": 42,
      "external_id": "row-42",
      "prompt": "What is the refund policy?",
      "input": null,
      "context": null,
      "output": "Refunds are available within 30 days.",
      "golden_answer": "30-day refund window.",
      "created_at": "2026-04-02T12:00:00Z",
      "updated_at": null
    }
  ],
  "runs": [],
  "evaluations": [],
  "last_run_id": null
}

{
  "id": 0,
  "user": { "id": 0, "email": "string" },
  "dataset_type_id": 0,
  "name": "string",
  "description": "string | null",
  "selected_metrics": "object | null",
  "structure": ["string"],
  "column_mappings": "object | null",
  "data_collection_id": "integer | null",
  "org_id": "integer | null",
  "project_id": "integer | null",
  "author_email": "string",
  "created_at": "date",
  "updated_at": "date | null",
  "dataset_type": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "string | null"
  },
  "records": [
    {
      "id": 0,
      "user_id": 0,
      "dataset_id": "integer | null",
      "external_id": "string | null",
      "prompt": "string | null",
      "input": "string | object | array | null",
      "context": "string | array | null",
      "output": "string | object | array | null",
      "golden_answer": "string | object | array | null",
      "created_at": "date",
      "updated_at": "date | null"
    }
  ],
  "runs": [],
  "evaluations": [],
  "last_run_id": "integer | null"
}

Each element of runs has this shape:

{
  "id": 0,
  "user": { "id": 0, "email": "string" },
  "api_key_id": 0,
  "dataset_id": "integer | null",
  "data_collection_id": "integer | null",
  "org_id": "integer | null",
  "project_id": "integer | null",
  "author_email": "string",
  "run_type": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "string"
  },
  "run_source": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "string"
  },
  "dataset": "DatasetResponse | null",
  "no_of_records": 0,
  "number_of_metrics": 0,
  "result": "number | null",
  "threshold": 0,
  "model_slug": "string | null",
  "alias": "string | null",
  "aggregate_results": "object | null",
  "total_cost": "string | null",
  "run_insight": "object | null",
  "started_at": "date",
  "finished_at": "date | null",
  "created_at": "date",
  "updated_at": "date | null",
  "is_gte_threshold": "boolean | null"
}

run_insight is null until an insight has been generated for the run. When present it includes id, run_id, user_id, content (with observations), model_slug, token counts, cost_raw, and timestamps.

When dataset on a run response is not null, it matches DatasetResponse:

{
  "id": 0,
  "user": { "id": 0, "email": "string" },
  "dataset_type_id": 0,
  "name": "string",
  "description": "string | null",
  "structure": ["string"],
  "selected_metrics": "object | null",
  "column_mappings": "object | null",
  "data_collection_id": "integer | null",
  "org_id": "integer | null",
  "project_id": "integer | null",
  "author_email": "string",
  "created_at": "date",
  "updated_at": "date | null"
}

Each element of evaluations has this shape:

{
  "id": 0,
  "user_id": 0,
  "run_id": 0,
  "record_id": 0,
  "metric_id": 0,
  "dataset_id": "integer | null",
  "result": "number | null",
  "threshold": 0,
  "explanation": "string | null",
  "model_slug": "string | null",
  "metric_args": "object | null",
  "started_at": "date",
  "finished_at": "date | null",
  "input_tokens": "integer | null",
  "output_tokens": "integer | null",
  "evaluation_cost": "string | null",
  "is_success": "boolean | null",
  "is_gte_threshold": "boolean | null",
  "created_at": "date",
  "updated_at": "date | null",
  "eval_metadata": "object | null"
}

metric_args reflects the per-metric arguments the evaluation actually ran with (resolved from dataset-level defaults plus any per-run override). eval_metadata is metric-specific extra signals (or null).

curl

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

Get datasets (partial)​

Get all datasets (paginated)​

Get dataset by id​

Get datasets (partial)

Get all datasets (paginated)

Get dataset by id