Skip to main content

Get data collections

This page documents read endpoints for data collections:

  • Paginated list: GET /data-collections
  • One data collection by id: GET /data-collections/{data_collection_id}

Get all data collections (paginated)​

Endpoint: GET /data-collections

Description

Returns a paginated list of data collections with an items array and a meta object. Each items entry is a summary view: nested datasets and nested runs. With a project-scoped API key, only collections assigned to that project are returned — see Introduction — API key scoping. Nested datasets you cannot access may be omitted from each summary while the collection itself remains visible.

Parameters

  • page — integer, default 1, minimum 1.
  • page_size — integer, default 10, between 1 and 10000.
  • shared — optional boolean. false returns only your own collections; true returns only collections shared with you; omit to return all you can access.

Error responses

  • 401, 422 — Auth or invalid page / page_size.
  • 404 — shared=true but the API key has no organization scope — solo account or private key (shared-only filtering is unavailable).
  • 500 — Server error listing collections.

Responses

  • 200 — JSON with items and meta:

Example response (200)

{
  "items": [
    {
      "id": 14,
      "user": { "id": 7, "email": "analyst@acme.com" },
      "name": "My bundle",
      "org_id": null,
      "project_id": null,
      "author_email": "analyst@acme.com",
      "datasets": [
        {
          "id": 1,
          "name": "Support QA - March",
          "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
        }
      ],
      "runs": [],
      "created_at": "2026-04-01T09:20:00Z",
      "updated_at": "2026-04-01T09:20:00Z"
    }
  ],
  "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" },
      "name": "string",
      "org_id": "integer | null",
      "project_id": "integer | null",
      "author_email": "string",
      "datasets": [
        {
          "id": 0,
          "name": "string",
          "description": "string | null",
          "user": { "id": 0, "email": "string" },
          "org_id": "integer | null",
          "project_id": "integer | null",
          "author_email": "string",
          "created_at": "date",
          "updated_at": "date | null"
        }
      ],
      "runs": [],
      "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"
  }
}

Each element of runs has this shape:

{
  "id": 0,
  "user": { "id": 0, "email": "string" },
  "run_type": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "string"
  },
  "run_source": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "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",
  "number_of_metrics": 0,
  "threshold": 0,
  "model_slug": "string | null",
  "alias": "string | null",
  "result": "number | 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.

curl

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

Get data collection by id​

Endpoint: GET /data-collections/{data_collection_id}

Description

Returns one data collection you can access, with full nested datasets and runs (including each run’s evaluations). Nested datasets (and nested dataset objects on runs) may be omitted when you cannot access them, while the collection and runs remain visible.

Parameters

Error responses

  • 401 — Authentication failed.
  • 404 — Collection not found or not accessible to your API key (including unassigned, assigned to a different project, or otherwise outside the key's project scope); or shared=true without organization scope (solo account or private API key).
  • 500 — Server error.

Responses

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

Example response (200)

{
  "id": 14,
  "user": { "id": 7, "email": "analyst@acme.com" },
  "name": "My bundle",
  "org_id": null,
  "project_id": null,
  "author_email": "analyst@acme.com",
  "datasets": [
    {
      "id": 1,
      "name": "Support QA - March",
      "description": "March support QA prompts",
      "user": { "id": 7, "email": "analyst@acme.com" },
      "org_id": null,
      "project_id": null,
      "author_email": "analyst@acme.com",
      "dataset_type_id": 1,
      "structure": ["prompt", "output", "golden_answer"],
      "selected_metrics": null,
      "column_mappings": null,
      "data_collection_id": 14,
      "created_at": "2026-03-30T10:00:00Z",
      "updated_at": null
    }
  ],
  "runs": [
    {
      "id": 991,
      "user": { "id": 7, "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"},
      "api_key_id": 12,
      "dataset_id": 1,
      "data_collection_id": 14,
      "org_id": null,
      "author_email": "analyst@acme.com",
      "dataset": {
        "id": 1,
        "user": { "id": 7, "email": "analyst@acme.com" },
        "dataset_type_id": 1,
        "name": "Support QA - March",
        "description": "March support QA prompts",
        "structure": ["prompt", "output", "golden_answer"],
        "selected_metrics": null,
        "column_mappings": null,
        "data_collection_id": 14,
        "org_id": null,
        "author_email": "analyst@acme.com",
        "created_at": "2026-03-30T10:00:00Z",
        "updated_at": null
      },
      "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": "2026-04-01T09:13:12Z",
      "created_at": "2026-04-01T09:12:00Z",
      "updated_at": null,
      "is_gte_threshold": true,
      "evaluations": [
        {
          "id": 5001,
          "user_id": 7,
          "run_id": 991,
          "record_id": 100,
          "metric_id": 3,
          "dataset_id": 1,
          "result": 86.0,
          "threshold": 70,
          "explanation": null,
          "model_slug": "gpt-4o",
          "started_at": "2026-04-01T09:12:05Z",
          "finished_at": "2026-04-01T09:12:10Z",
          "input_tokens": null,
          "output_tokens": null,
          "evaluation_cost": null,
          "is_success": true,
          "is_gte_threshold": true,
          "created_at": "2026-04-01T09:12:10Z",
          "updated_at": null,
          "eval_metadata": null
        }
      ]
    }
  ],
  "created_at": "2026-04-01T09:20:00Z",
  "updated_at": "2026-04-01T09:25:00Z"
}
{
  "id": 0,
  "user": { "id": 0, "email": "string" },
  "name": "string",
  "org_id": "integer | null",
  "project_id": "integer | null",
  "author_email": "string",
  "datasets": [],
  "runs": [],
  "created_at": "date",
  "updated_at": "date | null"
}

Each element of runs for get by id matches RunFullResponse (extends RunResponse: optional nested dataset, evaluations, and records).

{
  "id": 0,
  "user": { "id": 0, "email": "string" },
  "run_type": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "string"
  },
  "run_source": {
    "id": 0,
    "name": "string",
    "label": "string",
    "description": "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",
  "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",
  "evaluations": [],
  "records": []
}

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"
}

project_id on the collection, nested datasets, and nested runs reflects each resource's own project assignment when you are entitled to see it. Omitted or null when the resource is private, unassigned, or you lack project access. Nested members you cannot access are omitted from the response rather than returned with partial data.

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"
}

curl

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