Training runs

Allocates GPUs and returns the run ID that every other training route is keyed on. The body has two modes: start a new run from a base model, or resume from a saved state. Send one set of fields, not both.

Creating a run allocates GPUs and is not idempotent: retrying a timed-out request can allocate a second run. Send an Idempotency-Key header if your client retries automatically. See Errors and retries.

Returns your training runs as a paginated list. See Pagination for how limit, offset and the cursor object behave across list endpoints.

Passing path turns the call into a reverse lookup: given a nucleus:// checkpoint path, it returns the run that owns it.

Returns one run's metadata and its current step count.

Closes the run and releases its GPUs. An open run holds its allocation whether or not you are stepping it, so close runs as soon as you are finished with them.

Saved checkpoints are kept by default and remain loadable into new runs after this one is gone.

Returns the run's metric series: loss, gradient norm and learning rate per step. The platform records the full history server-side, so you do not need to reconstruct the curve from individual gradient responses, and a dropped connection loses nothing.

Evaluates the loss on a batch without computing gradients. Use it to measure held-out loss during a training loop, or to score data before deciding what to train on.

The batch is token IDs, not text: render your conversations with Render a conversation first. See Working with tokens.

The core gradient primitive. Runs the batch forward, computes the chosen loss and accumulates gradients on the run. Gradients accumulate across calls until you apply them with Optimizer step, so you can build large effective batches from several smaller requests.

Built-in loss functions cover supervised fine-tuning and reinforcement learning: cross-entropy, importance sampling, PPO, CISPO and DRO. For losses beyond these, use Custom-loss forward-backward.

As with Forward pass, inputs are token IDs. Render conversations with Render a conversation, or tokenize yourself; see Working with tokens.

Computes gradients for a loss you define yourself, as a two-leg exchange. The first leg runs the batch forward and returns per-token log probabilities together with an exchange_id. You compute the gradient of your loss with respect to those logprobs locally, then submit the per-token gradients back against the same exchange_id; the platform completes the backward pass and accumulates the result on the run, ready for Optimizer step.

The exchange is short-lived: expires_in in the first-leg response gives the window in seconds. Submit your gradients before it lapses, or start again with a fresh first leg.

Applies the accumulated gradients with an AdamW update and clears them, advancing the run by one step. Call it after one or more forward-backward calls.

Note that weight_decay defaults to 0.0, unlike PyTorch's AdamW. Set it explicitly if you are porting a training loop that relies on PyTorch's default.

Swaps saved weights into the live run without closing it or opening a new one. Use it to roll back to an earlier checkpoint mid-loop, or to continue from weights produced by a different run.