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 datasetsand nested runs.

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 user is not a member of an organization (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,
      "author_email": "analyst@acme.com",
      "datasets": [
        {
          "id": 1,
          "name": "Support QA - March",
          "user": { "id": 7, "email": "analyst@acme.com" },
          "org_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",
      "author_email": "string",
      "datasets": [
        {
          "id": 0,
          "name": "string",
          "user": { "id": 0, "email": "string" },
          "org_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",
  "author_email": "string",
  "number_of_metrics": 0,
  "threshold": 0,
  "model_slug": "string | null",
  "alias": "string | null",
  "result": "number | null",
  "aggregate_results": "object | null",
  "started_at": "date",
  "finished_at": "date | null",
  "created_at": "date",
  "updated_at": "date | null",
  "is_gte_threshold": "boolean | null"
}

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).

Parameters

Error responses

  • 401 — Authentication failed.
  • 404 — Collection not found or not accessible; or shared=true without organization membership.
  • 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,
  "author_email": "analyst@acme.com",
  "datasets": [
    {
      "id": 1,
      "name": "Support QA - March",
      "user": { "id": 7, "email": "analyst@acme.com" },
      "org_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",
        "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",
  "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, plus evaluations).

{
  "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",
  "author_email": "string",
  "dataset": "DatasetResponse | null",
  "number_of_metrics": 0,
  "result": "number | null",
  "threshold": 0,
  "model_slug": "string | null",
  "alias": "string | null",
  "aggregate_results": "object | null",
  "started_at": "date",
  "finished_at": "date | null",
  "created_at": "date",
  "updated_at": "date | null",
  "is_gte_threshold": "boolean | null",
  "evaluations": []
}

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",
  "structure": ["string"],
  "selected_metrics": "object | null",
  "column_mappings": "object | null",
  "data_collection_id": "integer | null",
  "org_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",
  "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"