---
title: Reports · API reference
url: https://docs.schemalabs.ai/api-reference/reports
description: List and retrieve held-out reports: the immutable trust artifact minted by every endpoint create, refresh, and upgrade, with its split, baseline, and snapshot.
---

# Reports

> List and retrieve held-out reports: the immutable trust artifact minted by every endpoint create, refresh, and upgrade, with its split, baseline, and snapshot.

Every endpoint create, refresh, and upgrade emits exactly one held-out report: the trust artifact. A report is immutable, names its split (method, sizes, seed), its baseline, its data snapshot, and its weakest slice, so a number never travels without provenance. Stateless runs also mint a run record in this listing (`kind: "run"`).

Report display names follow `{endpoint}.{base}.{op}.{YYYY-MM-DD}` (base abbreviated `s1`, `s2`), for example `churn.s2.upgrade.2026-08-14`. The stable reference is the `r_...` id. Reports are kept for the life of the organization; deleting an endpoint does not delete its reports.

## The report object

`score` with its `metric` name, then metric fields by task type: classification carries `auc` and `per_class`; regression carries `rmse`, `nrmse`, `r2`, and `quantile_calibration`; anomaly carries `precision`, `recall`, `pr_auc` where labels exist, or `score_separation` flagged unsupervised. Every report states a baseline.

**Attributes**

- `id` (string): `r_...`, immutable.
- `name` (string): Display name at mint time, `{endpoint}.{base}.{op}.{date}`. A later rename of the endpoint does not change past names.
- `endpoint` (string): Endpoint name at mint time.
- `endpoint_id` (string): The endpoint ID.
- `kind` (string): The operation that minted the report; `run` marks a stateless run record. One of: `create`, `refresh`, `upgrade`, `run`.
- `base` (string): Base evaluated.
- `pinned` (boolean): Starred reports float to the top of history. Pinning affects prominence, not retention. Set by starring on the platform’s Reports page.
- `target` (object): `column`, `task`, and `classes` for classification.
- `data` (object): `snapshot` (`dsv_...`), `version` timestamp, `rows`. The grade is tied to this snapshot and can expire on drift.
- `split` (object): `method` (`in_context_holdout`), `train_rows`, `test_rows`, `seed`, `stratified`, and `unit` (`entity` when the split is by matched entity).
- `metrics` (object): Task-appropriate metrics plus `baseline_majority` (or `baseline_mean`) and `lift_pp`.
- `confidence` (object): `calibrated` (confidences on Schema models are calibrated probabilities) and a `spread` note.
- `weakest_slice` (string): The slice with the lowest score, surfaced on purpose.
- `previous` (object | null): On upgrade reports: `{ report_id, base, score }` and `delta`.

```json
{
  "id": "r_8f3a",
  "name": "churn.s1.create.2026-03-10",
  "endpoint": "churn",
  "endpoint_id": "{endpoint_id}",
  "kind": "create",
  "base": "schema-1",
  "created_at": "2026-03-10T14:09:31Z",
  "pinned": true,
  "target": {
    "column": "crm_contacts.c3",
    "task": "classification",
    "classes": [
      "retained",
      "churned"
    ]
  },
  "data": {
    "snapshot": "dsv_2b81",
    "version": "2026-03-10 14:02",
    "rows": 22094
  },
  "split": {
    "method": "in_context_holdout",
    "train_rows": 17675,
    "test_rows": 4419,
    "seed": 42,
    "stratified": true,
    "unit": "entity"
  },
  "metrics": {
    "score": 0.942,
    "metric": "accuracy",
    "auc": 0.961,
    "baseline_majority": 0.71,
    "lift_pp": 23.2,
    "per_class": {
      "retained": 0.96,
      "churned": 0.88
    }
  },
  "confidence": {
    "calibrated": true,
    "spread": "most predictions high-confidence"
  },
  "weakest_slice": "tenure<3mo: 0.79",
  "cross_table": {
    "column_alignment": [
      {
        "a": "crm_contacts.c1",
        "b": "billing_db.c1",
        "attribute": "phone",
        "confidence": 0.96
      }
    ]
  },
  "estimate_note": "held-out is a creation-time estimate on unseen rows from the same snapshot; the live endpoint uses the full pinned data."
}
```

## Operations

### List reports

`GET /v2/reports` (scope: `read`)

Lists held-out reports, newest first, pinned first.

**Query parameters**

- `limit` (integer, default 20): Page size.
- `cursor` (string): Cursor from a previous page.

**Returns**

A page of report summaries.

**Example request (cURL)**

```bash
curl 'https://api.schemalabs.ai/v2/reports?limit=3' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"
```

**Example response (200)**

```json
{
  "reports": [
    {
      "id": "r_a7d0",
      "name": "churn.s2.upgrade.2026-08-14",
      "kind": "upgrade",
      "base": "schema-2",
      "metric": "accuracy",
      "score": 0.961,
      "delta": "+0.013",
      "pinned": false,
      "created_at": "2026-08-14T11:20:05Z"
    },
    {
      "id": "r_b5e1",
      "name": "churn.s1.refresh.2026-08-12",
      "kind": "refresh",
      "base": "schema-1",
      "metric": "accuracy",
      "score": 0.948,
      "pinned": false,
      "created_at": "2026-08-12T09:31:44Z"
    },
    {
      "id": "r_8f3a",
      "name": "churn.s1.create.2026-03-10",
      "kind": "create",
      "base": "schema-1",
      "metric": "accuracy",
      "score": 0.942,
      "pinned": true,
      "created_at": "2026-03-10T14:09:31Z"
    }
  ],
  "next_cursor": null,
  "total": 3
}
```

### Retrieve a report

`GET /v2/reports/:id` (scope: `read`)

Returns the full held-out report.

**Path parameters**

- `id` (string, required): `r_...`.

**Returns**

The [report object](#the-report-object).

**Example request (cURL)**

```bash
curl 'https://api.schemalabs.ai/v2/reports/r_8f3a' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"
```

**Example response (200)**

```json
{
  "id": "r_8f3a",
  "name": "churn.s1.create.2026-03-10",
  "endpoint": "churn",
  "endpoint_id": "{endpoint_id}",
  "kind": "create",
  "base": "schema-1",
  "created_at": "2026-03-10T14:09:31Z",
  "pinned": true,
  "target": {
    "column": "crm_contacts.c3",
    "task": "classification",
    "classes": [
      "retained",
      "churned"
    ]
  },
  "data": {
    "snapshot": "dsv_2b81",
    "version": "2026-03-10 14:02",
    "rows": 22094
  },
  "split": {
    "method": "in_context_holdout",
    "train_rows": 17675,
    "test_rows": 4419,
    "seed": 42,
    "stratified": true,
    "unit": "entity"
  },
  "metrics": {
    "score": 0.942,
    "metric": "accuracy",
    "auc": 0.961,
    "baseline_majority": 0.71,
    "lift_pp": 23.2,
    "per_class": {
      "retained": 0.96,
      "churned": 0.88
    }
  },
  "confidence": {
    "calibrated": true,
    "spread": "most predictions high-confidence"
  },
  "weakest_slice": "tenure<3mo: 0.79",
  "cross_table": {
    "column_alignment": [
      {
        "a": "crm_contacts.c1",
        "b": "billing_db.c1",
        "attribute": "phone",
        "confidence": 0.96
      }
    ]
  },
  "estimate_note": "held-out is a creation-time estimate on unseen rows from the same snapshot; the live endpoint uses the full pinned data."
}
```