Checkpoints

Checkpoints are the durable output of a training run. They come in two types: a training checkpoint captures the full state needed to resume training, and a sampler checkpoint holds servable weights you can point a sampler at. Every checkpoint has a nucleus:// path, for example nucleus://run_3Bz:train:0/sampler_weights/000240, which is the handle that samplers and Load state accept.

Checkpoints stay in your account until they expire or you delete them. Set ttl_seconds at creation, or adjust it later with Update checkpoint expiry, to control how long they are retained. When you want the weights outside the platform, use Export weights to convert them into a format you can load anywhere.

Create a checkpoint

POST/v1/training-runs/{run_id}/checkpointsscope: train

Writes a checkpoint from the run's current state. Pass type: "training" for a resumable checkpoint you can restore with Load state, or type: "sampler" to emit servable weights. The returned path is what Create a sampler and Load state accept.

Path parameters

run_idstringrequired

ID of the training run to checkpoint.

Body parameters

typestringrequired

What to write: training for a resumable checkpoint or sampler for servable weights.

namestringrequired

Name for the checkpoint. Names are stable, so you can save to the same name across steps.

ttl_secondsinteger or null

How long to retain the checkpoint. Pass null to keep it until you delete it.

overwriteboolean

Replace an existing checkpoint with the same name. training checkpoints only.

Send an Idempotency-Key header if your client retries automatically, so a timed-out request does not write a duplicate checkpoint. See Errors and retries.

curl https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints \
  -H "Authorization: Bearer $NUCLEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "sampler", "name": "000240", "ttl_seconds": null}'

201 Created

{
  "checkpoint_id": "ckpt_000240",
  "checkpoint_type": "sampler",
  "path": "nucleus://run_3Bz:train:0/sampler_weights/000240",
  "bytes": 268435456,
  "expires_at": null
}

List checkpoints for a run

GET/v1/training-runs/{run_id}/checkpointsscope: read

Returns every checkpoint saved by one run. Training and sampler checkpoints are listed together, each tagged with its checkpoint_type.

Path parameters

run_idstringrequired

ID of the training run.

curl https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

200 OK

{
  "checkpoints": [
    {
      "checkpoint_id": "ckpt_000240",
      "checkpoint_type": "sampler",
      "bytes": 268435456
    }
  ]
}

List all checkpoints

GET/v1/checkpointsscope: read

Returns every checkpoint in your account across all runs, newest first. Pass path to resolve one checkpoint from its nucleus:// path, including the base model and LoRA rank it was trained against. See Pagination for how limit, offset and the cursor object behave across list endpoints.

Query parameters

limitintegerdefault: 100

Maximum number of checkpoints to return.

offsetintegerdefault: 0

Number of checkpoints to skip from the start of the list.

pathstring

A nucleus:// checkpoint path. When set, the response resolves that single checkpoint.

curl "https://api.nucleus-ai.io/v1/checkpoints?limit=100" \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

200 OK

{
  "checkpoints": [
    {
      "training_run_id": "run_3Bz",
      "checkpoint_id": "ckpt_000240",
      "base_model": "Qwen/Qwen3-8B",
      "lora_rank": 32
    }
  ],
  "cursor": { "total_count": 128 }
}

Retrieve a checkpoint

GET/v1/training-runs/{run_id}/checkpoints/{checkpoint_id}scope: read

Returns one checkpoint: its type, visibility, expiry and size.

Path parameters

run_idstringrequired

ID of the training run that owns the checkpoint.

checkpoint_idstringrequired

ID of the checkpoint.

curl https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints/ckpt_000240 \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

200 OK

{
  "checkpoint_id": "ckpt_000240",
  "checkpoint_type": "sampler",
  "visibility": "private",
  "expires_at": null,
  "bytes": 268435456
}

Get a download URL

GET/v1/training-runs/{run_id}/checkpoints/{checkpoint_id}/archive-urlscope: read

Returns a time-limited signed URL for the checkpoint's raw archive. Download the bytes directly from that URL: they do not stream through the API host. The URL expires at expires_at, so fetch a fresh one rather than storing it.

The archive is the platform's internal format. To get weights in a format you can load elsewhere, use Export weights instead.

Path parameters

run_idstringrequired

ID of the training run that owns the checkpoint.

checkpoint_idstringrequired

ID of the checkpoint.

curl https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints/ckpt_000240/archive-url \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

200 OK

{
  "url": "https://storage.nucleus-ai.io/...",
  "expires_at": "2026-07-27T10:14:02Z"
}

Export weights

POST/v1/training-runs/{run_id}/checkpoints/{checkpoint_id}/exportscope: train

Converts a checkpoint into a format you can load outside the platform: a LoRA adapter, merged safetensors, or GGUF. This is how you take your weights with you and run them anywhere, including fully offline and on-premises deployments.

The export runs asynchronously and returns 202 Accepted with an operation ID. Poll Poll an operation or register a webhook to be notified when it completes.

Path parameters

run_idstringrequired

ID of the training run that owns the checkpoint.

checkpoint_idstringrequired

ID of the checkpoint to export.

Body parameters

formatstringrequired

Output format: lora-adapter, merged-safetensors or gguf.

destinationstringrequired

Where to deliver the export: signed-url or hf-hub.

hf_repostring

Target Hugging Face repository. Required when destination is hf-hub.

Exports allocate work, so send an Idempotency-Key header if your client retries automatically. See Errors and retries.

curl https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints/ckpt_000240/export \
  -H "Authorization: Bearer $NUCLEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "merged-safetensors", "destination": "signed-url"}'

202 Accepted

{
  "operation": "op_91c4",
  "format": "merged-safetensors",
  "status": "running"
}

Update checkpoint expiry

PATCH/v1/training-runs/{run_id}/checkpoints/{checkpoint_id}scope: train

Sets or clears a checkpoint's expiry. The new TTL is counted from the moment of the call, not from the checkpoint's creation. Pass null to clear the expiry and keep the checkpoint until you delete it.

Expiry is the main lever on storage spend: shorten it on intermediate checkpoints you no longer need, and clear it on the ones you serve from.

Path parameters

run_idstringrequired

ID of the training run that owns the checkpoint.

checkpoint_idstringrequired

ID of the checkpoint.

Body parameters

ttl_secondsinteger or nullrequired

Seconds until the checkpoint expires, counted from now. null clears the expiry.

curl -X PATCH https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints/ckpt_000240 \
  -H "Authorization: Bearer $NUCLEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 2592000}'

200 OK

{
  "checkpoint_id": "ckpt_000240",
  "expires_at": "2026-08-26T09:14:02Z"
}

Publish a checkpoint

PUT/v1/training-runs/{run_id}/checkpoints/{checkpoint_id}/visibilityscope: admin

Makes a checkpoint readable outside the owning account. Only the checkpoint's owner can publish it, and the key needs the admin scope. Review your data residency and sharing obligations before publishing weights trained on sensitive data.

Path parameters

run_idstringrequired

ID of the training run that owns the checkpoint.

checkpoint_idstringrequired

ID of the checkpoint to publish.

Body parameters

visibilitystringrequired

Must be public.

curl -X PUT \
  https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints/ckpt_000240/visibility \
  -H "Authorization: Bearer $NUCLEUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "public"}'

200 OK

{
  "checkpoint_id": "ckpt_000240",
  "visibility": "public"
}

Unpublish a checkpoint

DELETE/v1/training-runs/{run_id}/checkpoints/{checkpoint_id}/visibilityscope: admin

Returns a published checkpoint to private. Readers outside the owning account lose access immediately.

Path parameters

run_idstringrequired

ID of the training run that owns the checkpoint.

checkpoint_idstringrequired

ID of the checkpoint to unpublish.

curl -X DELETE \
  https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints/ckpt_000240/visibility \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

204 No Content

(empty body)

Delete a checkpoint

DELETE/v1/training-runs/{run_id}/checkpoints/{checkpoint_id}scope: train

Permanently deletes a checkpoint. There is no undo: the weights are gone and the checkpoint's nucleus:// path can no longer be loaded or served.

Deletion is addressed by run and checkpoint ID. If you only have a nucleus:// path, resolve it to IDs through List all checkpoints first.

Path parameters

run_idstringrequired

ID of the training run that owns the checkpoint.

checkpoint_idstringrequired

ID of the checkpoint to delete.

curl -X DELETE https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints/ckpt_000240 \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

204 No Content

(empty body)

Checkpoints

On this page