Core concepts

InstantML is built around a small set of training-loop concepts — once they are clear, the SDK, API, and dashboard all feel predictable.

How it works

Every InstantML integration follows the same five-step loop:

1. Init — im.init(project=...) creates a run inside a project.
2. Config — the config dict you pass to init records why this run differs from others.
3. Log — run.log({"train/loss": 0.42}, step=step) appends points to named metric series.
4. Finish — run.finish() marks the run complete.
5. View — open the dashboard to chart, search, and compare the run.

The rest of this page defines each noun in that loop, plus the surrounding concepts: workspaces, artifacts, checkpoint forks, rich objects, reports, and usage limits.

Workspace

A workspace is the top-level boundary in InstantML. It owns members, roles, billing, usage, API keys, reports, storage configuration, projects, and runs. Switching workspaces changes the context for every dashboard page and API route.

Project

A project groups related runs. Most teams use one project per model family, benchmark, environment, or product workflow.

Examples:

• cartpole
• mnist
• rank-scale-rl
• customer-support-finetune

Projects cannot be renamed, so pick names you can live with.

Projects are also a useful API-key boundary. Project-scoped keys can restrict SDK logging and reads to one project.

If you call instantml.init() without project=, the run lands in a shared project named `default`. You can filter into it like any other project.

Run

A run is one training, evaluation, sweep, import, or experiment execution.

Runs carry:

• Name and status.
• Start/end timing.
• Config values.
• Searchable tags and notes.
• Parent run and checkpoint fork context when the run was created from a checkpoint.
• Maintained metric summaries.
• Source metadata when the SDK can capture it.
• Artifacts, checkpoints, rich objects, logs, traces, and media.

If you call instantml.init() without name=, the server assigns a unique name of the form <adjective>-<noun>-<sequence> — for example bold-falcon-1 or serene-glacier-42 — where the sequence is the run's 1-indexed position in its project.

Metric

A metric is a named scalar time series logged at a numeric step.

Good metric keys are stable and namespaced:

Use consistent names across runs so the dashboard can compare them directly.

Scalar metrics become line charts in Metrics, Run Detail, and Runs workspace line panels. Compare shows scalar metrics as sortable values and columns. The Runs workspace can also summarize the runs you have loaded with latest-value bar panels, value histogram panels, dot plots, scatter plots, and seed/group distribution panels. Scatter panels combine any two numeric run fields — metric aggregates, config values, metadata, duration, or created time. Distribution panels group a numeric run field by a categorical config value, metadata field, status, or first tag.

Choose the data shape before logging so each dashboard surface can stay fast and readable:

Step

Step is the x-axis coordinate for metric series. Steps must be finite, nonnegative numbers. The SDK warns when a lower step is logged for the same metric after a higher step.

Typical step choices:

• Global optimizer step.
• Environment step.
• Epoch.
• Evaluation checkpoint number.

Pick one convention per project and keep it boring.

Config

Config is run-level context that should explain why a run differs from others.

Good config fields include:

• seed
• model
• dataset
• optimizer.lr
• batch_size
• algorithm
• checkpoint_source

Configs appear in Run Detail, Compare, and search context.

Tags and notes

Tags and notes are first-class run identity fields.

Use tags for compact labels:

run.set_tags(["baseline", "ppo", "ready-for-compare"])

Use notes for human context:

run.set_notes("Reward improved, but entropy dipped late.")

Both are searchable in the dashboard and visible in comparison workflows. Use bare text for broad matching, tag:baseline for exact tag matching, and notes:"ready for compare" when the note text should be the filter target.

Artifact

Artifacts track files or external references associated with a run.

Use artifacts for:

• Model checkpoints.
• Prediction files.
• Confusion matrices.
• Eval reports.
• Rollout videos.
• Audio samples.
• Dataset profiles.

Stored artifact bytes are uploaded through the API and served back through a same-origin download route. External references remain copyable metadata.

Checkpoint fork

A checkpoint fork is a linked child run created from a source run and checkpoint artifact. Forking records provenance only. It does not start training, copy metrics, or copy artifacts. Attach the SDK to the child run when you are ready to resume or retry training.

Rich object

Rich objects are structured logged values for dashboard previews.

Current public object types include:

• Tables.
• Histograms.
• Binary classification evaluation bundles.
• Media objects linked to artifacts.

The dashboard fetches object manifests separately from run summaries so hidden tabs do not load large object payloads by accident.

Rich-object histograms are previewed in Run Detail and artifact/object surfaces. They are separate from Runs workspace value histogram panels, which plot scalar metric summary values across the runs currently selected or loaded in the workspace. Saved logged-histogram timeline panels can read one selected run's histogram objects by explicit key. Classification evaluation bundles render typed PR/ROC, confusion-matrix, per-class, and optional prediction previews.

Keep arrays, tables, media, confusion matrices, and prediction examples as rich objects. Scalar metrics should stay finite numeric values so summary panels and comparisons do not need to fetch object payloads or full metric histories.

Report

A report is a workspace-scoped writeup with block content, live dashboard panels, share links, and Markdown export. Reports are for experiment decisions, checkpoint reviews, and summaries that need narrative context beyond a saved dashboard view.

Usage and limits

Usage is scoped to the current workspace.

Important limit types:

• Metric points in the current UTC calendar month.
• Retained projects and runs.
• Retained storage.
• Seats.
• API keys.

When a blocking limit is reached, write endpoints return a plan-limit error instead of silently accepting a partial write. See Pricing, limits, and billing for the exact numbers per plan.

Next steps

• Quickstart
• Log from Python
• Runs workspace
• Compare runs
• Pricing, limits, and billing