Schema reference

Public storage-shape reference for core InstantML entities and metric tables.

This page documents the stable public shapes behind exports, imports, API responses, and dashboard behavior; physical database details can evolve, but these entity meanings hold.

Project

{
  "id": "uuid",
  "org_id": "uuid",
  "name": "cartpole",
  "description": null,
  "created_at": "2026-05-16T00:00:00Z"
}

A project groups runs inside one workspace. SDK run creation can create a project automatically unless a project-scoped API key forbids it.

Run

{
  "id": "uuid",
  "org_id": "uuid",
  "project_id": "uuid",
  "project": "cartpole",
  "name": "ppo-seed-42",
  "status": "running",
  "config": { "seed": 42 },
  "tags": ["baseline"],
  "metadata": { "notes": "first pass" },
  "created_at": "2026-05-16T00:00:00Z",
  "started_at": "2026-05-16T00:00:00Z",
  "finished_at": null
}

Stored run statuses:

running
finished
failed

The dashboard derives a display status that can also show stopping and stopped while a cooperative stop request is in flight; the stored status contract above does not change.

Forked runs carry three optional lineage fields: parent_run_id, forked_from_step, and forked_from_artifact_id. Notes are stored in run metadata and treated as searchable run identity by the dashboard.

Metric point

{
  "key": "eval/accuracy",
  "step": 1,
  "value": 0.9,
  "created_at": "2026-05-16T00:00:00Z"
}

Metric values must be finite numbers (negative values such as losses or rewards are allowed); steps must be finite and nonnegative. A batch can include up to 1,000 metric keys for one run and step.

Rank metric point

{
  "key": "train/loss",
  "step": 1,
  "rank": 0,
  "local_rank": 0,
  "world_size": 8,
  "weight": 1024,
  "value": 0.12
}

Rank metrics power distributed-training reducers, coverage, heatmaps, and outlier views. See Distributed training.

Attribute

{
  "id": 1,
  "org_id": "uuid",
  "run_id": "uuid",
  "path": "config/optimizer",
  "type": "string_series",
  "step": 1,
  "logged_at": "2026-05-16T00:00:00Z",
  "value": "adam",
  "summary": {},
  "artifact_id": null,
  "created_at": "2026-05-16T00:00:00Z"
}

Attributes hold typed non-scalar context. Supported type values:

config
float_series
string_series
file
file_series
histogram_series
tag

Rich object

{
  "key": "eval/samples",
  "kind": "table",
  "step": 1,
  "artifact_id": null,
  "metadata": {},
  "summary": { "columns": ["prompt", "score"] }
}

Supported kinds:

table
image
video
audio
histogram (stored and listed as histogram_series)
classification_eval

Media kinds (image, video, audio) require an artifact_id pointing at the uploaded bytes. Table row previews are paginated separately. Histogram values use finite bins and nonnegative counts. classification_eval values are compact binary-classification bundles with bounded PR/ROC curves, a 2x2 confusion matrix, per-class metrics, and optional prediction rows.

Artifact

{
  "id": "uuid",
  "org_id": "uuid",
  "run_id": "uuid",
  "type": "checkpoint",
  "name": "policy.pt",
  "uri": "instantml://artifacts/uuid",
  "step": 1000,
  "size_bytes": 42000000,
  "sha256": "hex",
  "mime_type": "application/octet-stream",
  "storage_backend": "r2",
  "metadata": {},
  "created_at": "2026-05-16T00:00:00Z"
}

storage_backend is local or r2 for server-managed stored bytes and external for metadata-only references to your own storage. Stored bytes always surface an opaque instantml://artifacts/<id> URI in public responses; external references keep their original URI.

Export envelope

Exports are explicit and bounded:

{
  "version": 1,
  "exported_at": "2026-05-16T00:00:00Z",
  "organizations": [],
  "projects": [],
  "runs": [],
  "metric_series": [],
  "metrics": [],
  "attributes": [],
  "artifacts": [],
  "table_object_rows": [],
  "imports": [],
  "limits": {},
  "truncated": false
}

limits reports the per-section export caps that were applied. When truncated is true, at least one section hit its cap — narrow the filters before treating the export as a complete archive.