# Artifacts and checkpoints

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()`.

> **Info:** An **artifact** is a file or external reference attached to a run — a model file, an eval report, a rollout video. A **checkpoint** is an artifact that marks a restart point for training. See [core concepts](/docs/concepts/core-concepts.md) for how artifacts relate to runs and projects.

## 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.

> **Note:** `artifact_type` accepts `checkpoint`, `file`, or `rollout`. Use metadata and MIME type for finer-grained labels such as image, audio, report, model, or table.

## 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.

> **Note:** Rich media helpers need both `artifacts:write` and `sdk:ingest`, and they are not supported in `upload_mode="spool"` — see [media objects](/docs/sdk/rich-objects#log-media-objects.md) for the details.

## 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

- [Browse artifacts and files in the dashboard](/docs/dashboard/artifacts-files.md)
- [Resume training from checkpoints](/docs/dashboard/checkpoints.md)
- [Log tables, histograms, and media](/docs/sdk/rich-objects.md)
- [Query runs, metrics, and objects](/docs/sdk/querying-data.md)
- [Artifacts API reference](/docs/api/artifacts.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) (current page)
- [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)

### API Reference

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