InstantMLDocs

SDK logging

Create runs, log metrics, and finish cleanly from your training loop.

Open .md

Create a run at the start of your script, log metrics inside the loop, and finish the run when the script ends.

Create a run

python
import instantml as im

run = im.init(
    project="mnist",
    name="cnn-seed-7",
    config={"seed": 7, "optimizer": "adam"},
    tags=["baseline"],
    notes="First CNN baseline.",
)

Both project and name are optional:

FieldDefault when omittedNotes
project"default"A shared bucket. The project is created on first use.
name<adjective>-<noun>-<sequence>Assigned by the server, e.g. bold-falcon-1. The adjective/noun pair is picked at random per create; the sequence is the run's 1-indexed position in its project.

The auto-name is assigned server-side and shown in the dashboard; the run handle does not expose it. Use run.run_id when a script needs a stable identifier:

python
run = im.init()
print(run.run_id)

Pass an explicit name= whenever the run is meaningful long-term, such as a sweep cell or experiment cohort. The auto-name is for quick iteration and smoke tests.

Use im.Client(...) when you want to reuse a base URL, timeout, or API key across several runs:

python
client = im.Client(
    base_url="https://api.instantml.ai",
    timeout=2.0,
    api_key="instantml_...",
)

run = client.init(project="cartpole", name="ppo-seed-42")

Log scalar metrics

run.log(...) is the ergonomic API. If step is omitted, the SDK auto-increments from 1. If step is provided, it uses that value and advances the implicit counter to at least that step.

python
run.log({"train/reward": 100.0})
run.log({"train/loss": 0.12, "eval/accuracy": 0.91}, step=2)

Metric steps must be finite, nonnegative numbers. The UI expects each metric's step values to move forward over time. See Metrics and steps for naming and batching guidance.

Add run context

python
run.log_config({"optimizer": {"lr": 0.0003}})
run.add_tags(["ready-for-compare"])
run.set_notes("Reward improved but entropy dipped late.")

Configs appear in Run Detail and Compare. Tags and notes are searchable in the run list and editable from the dashboard.

Finish cleanly

python
run.finish()

You can also use a context manager:

python
with im.init(project="mnist", name="cnn-seed-7", config={"seed": 7}) as run:
    run.log({"train/loss": 0.42}, step=1)

If the block exits normally, the SDK finishes the run as finished. If an exception escapes the block, the SDK marks it as failed.

By default, run creation starts in the background so training scripts avoid waiting on startup. Call run.wait_for_init() before expensive work when you want credential or connectivity failures to surface immediately.

Choose an upload mode

The default async mode queues writes locally and drains them in the background. For batching, offline replay, or process-isolated spooling, see Buffering, offline replay, and spool mode.

Next steps