API reference · Reports

Reports

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.

Routes

objectThe report object
GET/v2/reports
GET/v2/reports/:id

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.

The report objectjson

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

Attributes

idstring
r_..., immutable.
namestring
Display name at mint time, {endpoint}.{base}.{op}.{date}. A later rename of the endpoint does not change past names.
endpointstring
Endpoint name at mint time.
endpoint_idstring
The endpoint ID.
kindstring
The operation that minted the report; run marks a stateless run record.
createrefreshupgraderun
basestring
Base evaluated.
pinnedboolean
Starred reports float to the top of history. Pinning affects prominence, not retention. Set by starring on the platform’s Reports page.
targetobject
column, task, and classes for classification.
dataobject
snapshot (dsv_...), version timestamp, rows. The grade is tied to this snapshot and can expire on drift.
splitobject
method (in_context_holdout), train_rows, test_rows, seed, stratified, and unit (entity when the split is by matched entity).
metricsobject
Task-appropriate metrics plus baseline_majority (or baseline_mean) and lift_pp.
confidenceobject
calibrated (confidences on Schema models are calibrated probabilities) and a spread note.
weakest_slicestring
The slice with the lowest score, surfaced on purpose.
previousobject | null
On upgrade reports: { report_id, base, score } and delta.

List reports

GET/v2/reports

scope read

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

GET/v2/reports

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

import os
import requests

SCHEMA_API_KEY = os.environ["SCHEMA_API_KEY"]

r = requests.get(
    "https://api.schemalabs.ai/v2/reports?limit=3",
    headers={"Authorization": f"Bearer {SCHEMA_API_KEY}"},
)
r.raise_for_status()
result = r.json()

const res = await fetch('https://api.schemalabs.ai/v2/reports?limit=3', {
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Schema API error ${res.status}`);
const result = await res.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
}

Query parameters

limitintegerdefault 20
Page size.
cursorstring
Cursor from a previous page.

Returns

A page of report summaries.

Retrieve a report

GET/v2/reports/:id

scope read

Returns the full held-out report.

GET/v2/reports/:id

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

import os
import requests

SCHEMA_API_KEY = os.environ["SCHEMA_API_KEY"]

r = requests.get(
    "https://api.schemalabs.ai/v2/reports/r_8f3a",
    headers={"Authorization": f"Bearer {SCHEMA_API_KEY}"},
)
r.raise_for_status()
result = r.json()

const res = await fetch('https://api.schemalabs.ai/v2/reports/r_8f3a', {
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Schema API error ${res.status}`);
const result = await res.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."
}

Path parameters

idstringrequired
r_....

Returns

The report object.