InstantMLDocs

Artifacts and checkpoints

Log files, artifacts, checkpoints, rollouts, and media from Python.

Open .md

Attach files, checkpoints, versioned artifact collections, and rollout media to a run so the evidence lives next to the metrics that produced it.

Prerequisites

  • An API key with artifacts:write for artifact and checkpoint routes. Add sdk:ingest when the same key also logs metrics, rich objects, or attaches to runs.
  • Add export:read when you fork runs or resolve artifacts through im.Api().

Log a metadata artifact

Use log_artifact(...) when the bytes are stored elsewhere and you want to record an external reference.

python
run.log_artifact(
    name="eval-report",
    uri="s3://bucket/evals/report.json",
    artifact_type="file",
    step=10,
    metadata={"kind": "eval-report"},
)

Upload a local file

Use upload_file(...) when InstantML should store the file bytes.

python
artifact = run.upload_file(
    "outputs/confusion_matrix.png",
    name="confusion-matrix",
    artifact_type="file",
    step=10,
)

The SDK records size and SHA-256 metadata, then uploads through the API. The artifact appears in the run's Files section and the Artifacts tab.

Version artifacts

Use VersionedArtifact when a dataset, model, or checkpoint package needs a stable manifest, latest/best aliases, and lineage.

python
import instantml as im

run = im.init(project="cartpole")

artifact = im.VersionedArtifact(
    "policy-checkpoints",
    type="model",
    metadata={"framework": "torch"},
)
artifact.add_file("checkpoints/policy.pt", name="checkpoint.pt")

logged = run.log_versioned_artifact(
    artifact,
    step=1000,
    aliases=["best"],
    ttl_days=30,
)

run.finish()

log_artifact(artifact, aliases=[...], ttl_days=...) also accepts a VersionedArtifact, and the older log_artifact(name, uri, ...) raw-artifact call keeps working.

Consume an artifact from another run

Resolve a version by name and alias, then record the dependency and download the files.

python
api = im.Api()
dataset = api.artifact("training-data:latest", type="dataset", project="cartpole")

run = im.init(project="cartpole")
run.use_artifact(dataset)
dataset.download("inputs/training-data")
run.finish()

LoggedArtifact.download(...) keeps downloaded paths inside the output directory. promote(alias="best", reason="...") moves a custom alias, and delete(delete_aliases=True, reason="...") requests a soft delete — both need a key with the artifacts:manage scope. The SDK sends the API's required confirmation fields for these destructive or mutable operations.

Log checkpoints

Use the checkpoint helpers when the file is a restart point for training. For an external reference:

python
run.log_checkpoint(
    name="policy-step-1000",
    uri="s3://bucket/checkpoints/policy.pt",
    step=1000,
)

For local checkpoint bytes:

python
run.log_checkpoint_file(
    "checkpoints/policy.pt",
    name="policy-step-1000",
    step=1000,
)

Checkpoint metadata and checkpoint byte uploads use artifact routes, so they need artifacts:write. Use CheckpointPolicy(every_steps=N) in loops that save on a fixed interval.

Fork and resume from a checkpoint

The dashboard can create a linked fork from a checkpoint artifact. The fork is only a child run record — it does not start training or copy existing metrics. Attach the SDK to the child run when your resume script is ready to log.

python
import instantml as im

api = im.Api()
child = api.fork_run(
    "source-run-id",
    checkpoint_artifact_id="artifact-id",
    step=1000,
    name="retry-from-step-1000",
)

run = im.attach_run(child["id"])
run.log({"train/loss": 0.1}, step=1001)
run.finish()

Api.fork_run(...) sends a stable idempotency key by default, so retrying the same fork request does not create duplicates.

Forking through the API needs both export:read and sdk:ingest. The attached child run validates with export:read by default; pass validate=False only for intentionally write-only credentials or offline attach flows.

Log rollouts and video

python
run.log_rollout("eval-rollout", "s3://bucket/eval.mp4", step=1000)
run.log_video("rollout.mp4", "s3://bucket/rollout.mp4", step=1000)

These calls create metadata artifacts for externally stored media. To store bytes through InstantML for same-origin preview and download, upload the local file:

python
run.upload_file("outputs/rollout.mp4", artifact_type="rollout", step=1000)

Use rich media objects when you want a local media file uploaded and linked as previewable evidence inside Run Detail:

python
run.log_objects(
    {"eval/rollout": im.Video(path="outputs/rollout.mp4", caption="Evaluation rollout")},
    step=1000,
)

Stored same-origin media previews in the dashboard when the browser supports the MIME type. External object-store references remain copy/download metadata only.

Find artifacts in the dashboard

  • Run Detail summary and Files section for raw run artifacts.
  • Artifacts tab for versioned collections, manifests, lineage, and raw run artifacts.
  • Compare artifact context.
  • API snippets for download and copy workflows.

Raw object-storage URLs are not shown in the dashboard when the API stores bytes for the workspace.

Next steps