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 (may be null), org_id, data_collection_id, project_id, permissions, author_email, created_at, and updated_at (not full rows, metrics, records, or extra-column definitions). user is null when the dataset has no individual owner. permissions is computed for this caller — see Introduction — Permissions. The example is a private dataset you own, read with a private API key, so can_share is false. With a project-scoped API key, only datasets assigned to that project are returned — see Introduction — API key scoping.

Parameters

• shared — optional boolean. The value must be the word true or false, any letter case (TRUE and FALSE are valid). Surrounding whitespace is not trimmed. 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.
• 422 — shared is present and is not the word true or false (any letter case). Surrounding whitespace and other spellings (yes, y, t, on, 1, no, n, f, off, 0) are rejected. detail[0].loc is ["query", "shared"] and detail[0].msg is "Value error, Value must be true or false.".
• 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,
    "data_collection_id": null,
    "project_id": null,
    "permissions": {
      "can_edit": true,
      "can_delete": true,
      "can_share": false,
      "can_assign_project": false,
      "can_move_collection": true
    },
    "author_email": "analyst@acme.com",
    "created_at": "2026-03-30T10:00:00Z",
    "updated_at": "2026-03-30T10:00:00Z"
  }
]

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. Each item includes an extra_columns array describing user-defined free-text columns on that dataset (empty when none are defined); see Extra columns. Each item includes permissions for this caller — see Introduction — Permissions. The example is a private dataset you own, read with a private API key, so can_share is false. With a project-scoped API key, only custom datasets assigned to that project are returned — see Introduction — API key scoping. A proprietary dataset_type_id returns the whole proprietary catalog and is not locked to the key's project. user is null when the dataset has no individual owner.

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 2; same query shape as dataset_type_id=2). Valid ids are returned by GET /dataset-types.
• shared — optional boolean. The value must be the word true or false, any letter case (TRUE and FALSE are valid). Surrounding whitespace is not trimmed. 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 that match at least one listed shortname if that metric appears in default_selected_metrics or was used in any evaluation on a run for that dataset (subject to the same access filters as the list). Map keys on the dataset are shortnames, not metric ids.
• 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, invalid data_collection_ids, or invalid shared. shared accepts only true or false (any letter case). Surrounding whitespace and other spellings (yes, y, t, on, 1, no, n, f, off, 0) return 422 ("Value error, Value must be true or false."; detail[0].loc is ["query", "shared"]).
• 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": 2,
      "name": "support_qa_march.csv",
      "description": "March support QA prompts",
      "default_selected_metrics": {
        "ans_corr": { "threshold": 70, "metric_args": null },
        "faith": { "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,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_share": false,
        "can_assign_project": false,
        "can_move_collection": true
      },
      "author_email": "analyst@acme.com",
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-04-01T10:00:00Z",
      "extra_columns": [
        { "id": "col_aabbccdd", "label": "Notes", "type": "text" }
      ]
    }
  ],
  "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" } | null,
      "dataset_type_id": 0,
      "name": "string",
      "description": "string | null",
      "default_selected_metrics": "object | null",
      "structure": ["string"],
      "column_mappings": "object | null",
      "data_collection_id": "integer | null",
      "org_id": "integer | null",
      "project_id": "integer | null",
      "permissions": {
        "can_edit": "boolean",
        "can_delete": "boolean",
        "can_share": "boolean",
        "can_assign_project": "boolean",
        "can_move_collection": "boolean"
      },
      "author_email": "string",
      "created_at": "date",
      "updated_at": "date",
      "extra_columns": [
        { "id": "col_aabbccdd", "label": "string", "type": "text" }
      ]
    }
  ],
  "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. The dataset and each nested run include permissions for this caller (can_edit, can_delete, can_share, can_assign_project, can_move_collection) — see Introduction — Permissions. Nested runs on this payload do not include a dataset object. A dataset run reports can_share, can_assign_project, and can_move_collection as false. Each nested run includes alias (the run’s display name, or null when the run has none) and project_id (the run’s assigned project). Nested run project_id is null when the run is private, unassigned, or you are not entitled to see the project. A private key never receives an organization project id. The payload includes extra_columns (column definitions) and, on each record, extra_values (per-row free text keyed by column id). Manage columns with Create extra column and related endpoints; set values with Set record extra values. 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). On nested runs, evaluations, and records, api_key_id (runs) and user_id (evaluations and records) may be null — for example, org-shared runs can remain visible after the creating user's API keys are removed, with no associated API key id. user on the dataset is null when the dataset has no individual owner. user on each nested run is null when that run has no individual owner.

Parameters

• Path: dataset_id — integer.

Error responses

• 401 — Authentication failed.
• 404 — Unknown id, or a custom dataset that is unassigned, assigned to a different project, or outside the key's project. Those cases apply to custom datasets only. A proprietary id is returned when it exists and is not rejected for project scope. A custom dataset outside the key's project is 404 with Dataset with id {dataset_id} not found. — the same detail as an unknown id.
• 500 — Server error; Run type with name DATASET not found. when the dataset run type is unavailable.

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": 2,
  "name": "My evaluation set",
  "description": "Evaluation prompts for support QA",
  "default_selected_metrics": {
    "ans_corr": { "threshold": 70, "metric_args": null },
    "faith": { "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,
  "permissions": {
    "can_edit": true,
    "can_delete": true,
    "can_share": false,
    "can_assign_project": false,
    "can_move_collection": true
  },
  "author_email": "analyst@acme.com",
  "created_at": "2026-04-02T12:00:00Z",
  "updated_at": "2026-04-02T12:00:00Z",
  "extra_columns": [
    { "id": "col_aabbccdd", "label": "Notes", "type": "text" }
  ],
  "dataset_type": {
    "id": 2,
    "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": "2026-04-02T12:00:00Z",
      "extra_values": { "col_aabbccdd": "reviewer note" }
    }
  ],
  "runs": [
    {
      "id": 991,
      "user": { "id": 7, "email": "analyst@acme.com" },
      "api_key_id": 12,
      "dataset_id": 42,
      "data_collection_id": null,
      "org_id": null,
      "project_id": null,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_share": false,
        "can_assign_project": false,
        "can_move_collection": false
      },
      "author_email": "analyst@acme.com",
      "run_type": {
        "id": 2,
        "name": "dataset",
        "label": "Dataset",
        "description": "Run from dataset"
      },
      "run_source": {
        "id": 1,
        "name": "api",
        "label": "API",
        "description": "Created via API"
      },
      "no_of_records": 1,
      "number_of_metrics": 2,
      "result": 83.5,
      "threshold": 70,
      "model_slug": "gpt-4o",
      "reasoning_level": null,
      "alias": "support-march",
      "aggregate_results": { "ans_corr": 86, "faith": 81 },
      "total_cost": "0.001200000000000",
      "started_at": "2026-04-02T12:05:00Z",
      "finished_at": "2026-04-02T12:06:12Z",
      "created_at": "2026-04-02T12:05:00Z",
      "updated_at": "2026-04-02T12:06:12Z",
      "is_gte_threshold": true
    }
  ],
  "evaluations": [],
  "last_run_id": 991
}

{
  "id": 0,
  "user": { "id": 0, "email": "string" } | null,
  "dataset_type_id": 0,
  "name": "string",
  "description": "string | null",
  "default_selected_metrics": "object | null",
  "structure": ["string"],
  "column_mappings": "object | null",
  "data_collection_id": "integer | null",
  "org_id": "integer | null",
  "project_id": "integer | null",
  "permissions": {
    "can_edit": "boolean",
    "can_delete": "boolean",
    "can_share": "boolean",
    "can_assign_project": "boolean",
    "can_move_collection": "boolean"
  },
  "author_email": "string",
  "created_at": "date",
  "updated_at": "date",
  "extra_columns": [
    { "id": "col_aabbccdd", "label": "string", "type": "text" }
  ],
  "dataset_type": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "string | null"
  },
  "records": [
    {
      "id": 0,
      "user_id": "integer | null",
      "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",
      "extra_values": { "col_aabbccdd": "string" }
    }
  ],
  "runs": [],
  "evaluations": [],
  "last_run_id": "integer | null"
}

extra_columns defaults to []. Each record's extra_values defaults to {}; keys follow extra_columns definition order. Set that order with Reorder extra columns. Column type is "text" today. Limits: up to 20 extra columns per dataset; label max 64 characters; value max 4000 characters; column id format col_ + 8 lowercase hex digits.

Each element of runs has this shape:

{
  "id": 0,
  "user": { "id": 0, "email": "string" } | null,
  "api_key_id": "integer | null",
  "dataset_id": "integer | null",
  "data_collection_id": "integer | null",
  "org_id": "integer | null",
  "project_id": "integer | null",
  "permissions": {
    "can_edit": "boolean",
    "can_delete": "boolean",
    "can_share": "boolean",
    "can_assign_project": "boolean",
    "can_move_collection": "boolean"
  },
  "author_email": "string",
  "run_type": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "string"
  },
  "run_source": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "string"
  },
  "dataset": "object | null",
  "no_of_records": 0,
  "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": "string | null",
  "started_at": "date",
  "finished_at": "date | null",
  "created_at": "date",
  "updated_at": "date",
  "is_gte_threshold": "boolean | null"
}

alias is the run’s display name, or null when the run has none. Nested run project_id is null when the run is private, unassigned, or you are not entitled to see the project. A private key never receives an organization project id.

GET /datasets/{dataset_id} does not nest a dataset on each run. When a run elsewhere includes one (a data collection's full payload), it has this shape. On that nested copy, user is null when the dataset has no individual owner, and permissions is present with every flag false — use the dataset's own object for the real flags.

{
  "id": 0,
  "user": { "id": 0, "email": "string" } | null,
  "dataset_type_id": 0,
  "name": "string",
  "description": "string | null",
  "structure": ["string"],
  "default_selected_metrics": "object | null",
  "column_mappings": "object | null",
  "data_collection_id": "integer | null",
  "org_id": "integer | null",
  "project_id": "integer | null",
  "permissions": {
    "can_edit": "boolean",
    "can_delete": "boolean",
    "can_share": "boolean",
    "can_assign_project": "boolean",
    "can_move_collection": "boolean"
  },
  "author_email": "string",
  "created_at": "date",
  "updated_at": "date",
  "extra_columns": [
    { "id": "col_aabbccdd", "label": "string", "type": "text" }
  ]
}

Each element of evaluations has this shape:

{
  "id": 0,
  "user_id": "integer | null",
  "run_id": 0,
  "record_id": "integer | null",
  "trace_id": "integer | null",
  "span_id": "string | null",
  "metric_id": 0,
  "dataset_id": "integer | 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",
  "input_tokens": "integer | null",
  "cached_read_tokens": "integer | null",
  "cache_write_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",
  "eval_metadata": "object | null"
}

record_id is the scored dataset row. trace_id and span_id are null on a dataset evaluation. metric_args reflects the per-metric arguments this evaluation actually ran with — from the dataset run request's selected_metrics when provided, otherwise from the dataset default_selected_metrics. input_tokens is the full prompt volume for the evaluation; cached_read_tokens and cache_write_tokens are subsets already counted inside input_tokens, not additional tokens on top. eval_metadata is metric-specific extra signals (or null).

curl

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