# Schema reference

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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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](/docs/sdk/distributed-training.md).

## Attribute

```json
{
  "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`

> **Note:** Requests accept an optional `timestamp` field when logging an attribute; the stored and returned field is `logged_at`.

## Rich object

```json
{
  "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

```json
{
  "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:

```json
{
  "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.

## Next steps

- [Storage model](/docs/architecture/storage-model.md)
- [Projects and runs API](/docs/api/projects-runs.md)
- [Metrics and series API](/docs/api/metrics-series.md)
- [Attributes and objects API](/docs/api/attributes-objects.md)
- [Import, export, and usage API](/docs/api/import-export-usage.md)

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md) (current page)

### API Reference

- [API Reference](/docs/api-reference.md)