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, nested runs, and nested traces. The collection and each nested child include permissions for this caller — see Introduction — Permissions. The example is a private collection you own, read with a private API key, so can_share is false. With a project-scoped API key, only collections assigned to that project are returned — see Introduction — API key scoping. Nested datasets, runs, and traces you cannot access are omitted from each summary while the collection itself remains visible. Each nested run's api_key_id may be null — for example, org-shared runs can remain visible after the creating user's API keys are removed. shared chooses which collections are returned. It does not split the nested datasets, runs, or traces again.

Parameters

  • page — integer, default 1, minimum 1. A page past the last page is clamped to the last page (not an empty page).
  • page_size — integer, default 10, between 1 and 10000.
  • 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 collections; true returns only collections shared with you; omit to return all you can access. Nested children stay every row you can see inside those collections.

Error responses

  • 401, 422 — Auth, invalid page / page_size, 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 — 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,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_share": false,
        "can_assign_project": false,
        "can_move_collection": true
      },
      "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,
          "data_collection_id": 14,
          "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"
        }
      ],
      "runs": [],
      "traces": [],
      "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",
      "permissions": {
        "can_edit": "boolean",
        "can_delete": "boolean",
        "can_share": "boolean",
        "can_assign_project": "boolean",
        "can_move_collection": "boolean"
      },
      "author_email": "string",
      "datasets": [
        {
          "id": 0,
          "name": "string",
          "description": "string | null",
          "user": { "id": 0, "email": "string" },
          "org_id": "integer | null",
          "data_collection_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"
        }
      ],
      "runs": [],
      "traces": [],
      "created_at": "date",
      "updated_at": "date"
    }
  ],
  "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 traces includes identity and filing fields only (no observability rollups such as start_time, duration_ms, span_count, error_count, tokens, or cost):

{
  "id": 0,
  "trace_id": "string (32-char hex)",
  "name": "string | null",
  "user": { "id": 0, "email": "string" } | null,
  "author_email": "string",
  "org_id": "integer | null",
  "data_collection_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"
  },
  "created_at": "date",
  "updated_at": "date"
}

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": "integer | null",
  "dataset_id": "integer | null",
  "trace_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",
  "number_of_metrics": 0,
  "threshold": 0,
  "model_slug": "string | null",
  "reasoning_level": "string | null",
  "alias": "string | null",
  "result": "number | 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"
}

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, records, and run_insight), plus nested traces as trace summaries (same shape as GET /traces list items — no spans). Nested runs may be dataset, custom, or trace runs (run_type.label "Trace", optional trace_id, optional nested trace). Trace-scored evaluations have record_id and nested record set to null. The collection and each nested dataset, run, and trace include permissions for this caller (can_edit, can_delete, can_share, can_assign_project, can_move_collection) — see Introduction — Permissions. A dataset run reports can_share, can_assign_project, and can_move_collection as false. A nested dataset on a run includes a permissions object whose flags are all false; read the matching entry in datasets for that dataset's flags. Nested datasets, runs, and traces you cannot access are omitted. A nested dataset on a run is omitted the same way, while the run stays. On nested runs, api_key_id may be null; on nested evaluations and records, user_id may be null (same org-shared run survival cases as the paginated list). When traces are attached to or detached from a collection, trace-backed runs’ data_collection_id stays aligned with their trace.

Parameters

  • Path: data_collection_id — integer.
  • shared — optional boolean. The value must be the word true or false, any letter case. Surrounding whitespace is not trimmed. Unlike the paginated list, this filters nested datasets, runs, and traces, not which collection is returned. false keeps children you own; true keeps children owned by someone else; omit it to return every child you can see. When shared is set, a dataset run whose dataset was filtered out is dropped from runs. Custom runs and trace runs stay. shared=true without organization scope is 404 (solo account or private key).

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 — 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,
  "permissions": {
    "can_edit": true,
    "can_delete": true,
    "can_share": false,
    "can_assign_project": false,
    "can_move_collection": true
  },
  "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,
      "permissions": {
        "can_edit": true,
        "can_delete": true,
        "can_share": false,
        "can_assign_project": false,
        "can_move_collection": true
      },
      "author_email": "analyst@acme.com",
      "dataset_type_id": 2,
      "structure": ["prompt", "output", "golden_answer"],
      "default_selected_metrics": null,
      "column_mappings": null,
      "extra_columns": [],
      "data_collection_id": 14,
      "created_at": "2026-03-30T10:00:00Z",
      "updated_at": "2026-03-30T10:00:00Z"
    }
  ],
  "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,
      "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",
      "dataset": {
        "id": 1,
        "user": { "id": 7, "email": "analyst@acme.com" },
        "dataset_type_id": 2,
        "name": "Support QA - March",
        "description": "March support QA prompts",
        "structure": ["prompt", "output", "golden_answer"],
        "default_selected_metrics": null,
        "column_mappings": null,
        "extra_columns": [],
        "data_collection_id": 14,
        "org_id": null,
        "project_id": null,
        "permissions": {
          "can_edit": false,
          "can_delete": false,
          "can_share": false,
          "can_assign_project": false,
          "can_move_collection": false
        },
        "author_email": "analyst@acme.com",
        "created_at": "2026-03-30T10:00:00Z",
        "updated_at": "2026-03-30T10:00:00Z"
      },
      "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},
      "started_at": "2026-04-01T09:12:00Z",
      "finished_at": "2026-04-01T09:13:12Z",
      "created_at": "2026-04-01T09:12:00Z",
      "updated_at": "2026-04-01T09:12:00Z",
      "is_gte_threshold": true,
      "evaluations": [
        {
          "id": 5001,
          "user_id": 7,
          "run_id": 991,
          "record_id": 100,
          "trace_id": null,
          "span_id": null,
          "metric_id": 3,
          "dataset_id": 1,
          "result": 86.0,
          "threshold": 70,
          "explanation": null,
          "model_slug": "gpt-4o",
          "reasoning_level": null,
          "started_at": "2026-04-01T09:12:05Z",
          "finished_at": "2026-04-01T09:12:10Z",
          "input_tokens": null,
          "cached_read_tokens": null,
          "cache_write_tokens": null,
          "output_tokens": null,
          "evaluation_cost": null,
          "is_success": true,
          "is_gte_threshold": true,
          "created_at": "2026-04-01T09:12:10Z",
          "updated_at": "2026-04-01T09:12:10Z",
          "eval_metadata": null
        }
      ]
    }
  ],
  "traces": [],
  "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",
  "permissions": {
    "can_edit": "boolean",
    "can_delete": "boolean",
    "can_share": "boolean",
    "can_assign_project": "boolean",
    "can_move_collection": "boolean"
  },
  "author_email": "string",
  "datasets": [],
  "runs": [],
  "traces": [],
  "created_at": "date",
  "updated_at": "date"
}

Each element of traces for get by id has the same JSON shape as one element of items from Get all traces (paginated) (no nested spans).

Each element of runs for get by id includes optional nested dataset, evaluations, and records with 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": "integer | null",
  "dataset_id": "integer | null",
  "trace_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",
  "dataset": "object | null",
  "trace": "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",
  "run_insight": "object | null",
  "evaluations": [],
  "records": []
}

When dataset on a run is not null, it has this shape:

{
  "id": 0,
  "user": { "id": 0, "email": "string" },
  "dataset_type_id": 0,
  "name": "string",
  "description": "string | null",
  "structure": ["string"],
  "default_selected_metrics": "object | null",
  "column_mappings": "object | null",
  "extra_columns": [
    { "id": "col_aabbccdd", "label": "string", "type": "text" }
  ],
  "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"
}

project_id on the collection, nested datasets, nested runs, and nested traces is null when the resource is private, unassigned, or you are not entitled to see the project. A private key never receives an organization project id. Nested members you cannot access are omitted from the response.

run_insight is null when the run has no insight. When present:

{
  "id": 0,
  "run_id": 0,
  "user_id": "integer | null",
  "content": {
    "observations": [
      {
        "severity": "critical | warning | info",
        "headline": "string",
        "detail": "string",
        "row_refs": "integer[] | null"
      }
    ]
  },
  "model_slug": "string | null",
  "input_tokens": "integer | null",
  "output_tokens": "integer | null",
  "cost_raw": "string | null",
  "created_at": "date",
  "updated_at": "date"
}

content.observations has three entries. row_refs is a list of 1-based record indexes, or null.

Collection datasets[] uses the nested dataset shape above (extra_columns defaults to []).

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

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. Each element of records has this shape:

{
  "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",
  "extra_values": { "col_aabbccdd": "string" },
  "created_at": "date",
  "updated_at": "date"
}

curl

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