Skip to main content
Experimental. Fine-tuning’s operations, fields, and limits can change between releases.
A fine-tuning job trains a base model with reinforcement learning on a fixed task set, scores the result on tasks it did not train on, and saves checkpoints you can run as a tuned model in any agent. You create a job, follow it while it runs, and read its checkpoints and scores.
Fine-tuning is enabled per organization. In an organization without it, every fine-tuning operation returns 400 invalid_request. Creating, resuming, renaming, and cancelling jobs, and asking questions about a run, needs the Developer or Admin role; the User role can read jobs, their metrics, rollouts, timeline, and checkpoints. API calls use a key from API keys. For the full end-to-end loop, see the Fine-tuning cookbook.

Set up

Samples read RECURSION_API_KEY from the environment. Install the CLI or the TypeScript SDK and create a client as shown in REST client setup. Each sample below shows one operation as cURL, CLI, and TypeScript, and the tabs stay in sync down the page. Console steps appear where the console has the action. The CLI takes each operation’s input as JSON on --input-stdin: path and query fields at the top level, headers such as Idempotency-Key by name, and the request body under body. Each SDK call returns { data, error }; the samples throw on error.

Start a run

Send the base model, the dataset, and any settings you want to change. Every omitted setting takes its default.
  1. In the sidebar, open Advanced, then Fine-tuning, and click New run.
  2. Under Run, optionally set a Name, and choose the Model and the Run type.
  3. Under Tasks, choose the Train set and Eval set; the dataset is fixed. Under Length, set Training steps.
  4. Open Customize for the other settings, grouped as Training, Evaluation, Stopping and checkpoints, Compute, and Limits, then click Start run.
The response is 201 Created with the queued job. Keep jobId.
Idempotency-Key is required. Send the same key and body again on a retry and you get the same job instead of a second one. Leave out name and the job is named after the model and the time it was created, such as Inkling 2 Small · 2026-11-20 18:08:03 UTC.
There is no cap on the turns of a rollout or on the steps of a run: a rollout ends when the model finishes, its context is full, or its replies cannot be parsed. See the reference for what each setting does.

Follow a run

Read the job for its status, phase, step, and rollout counts. Poll about every 30 seconds; a run takes minutes to days.
Open Advanced, then Fine-tuning, then the run. The page shows the phase, the rollouts of the current step, metric charts, checkpoints, and cost.
Stop polling when status is succeeded, failed, or cancelled. A running job whose progress.lastEventAt is long past is stalled; see Troubleshooting. Each collection can be followed without rereading it. Pass what you last read: When attempt changes, the new attempt deletes and rewrites metrics and rollouts from the step it resumed at, just before its compute is created. Wait until progress.phase has left queued, then read those collections again from that step (the resume event’s step, or 0) and replace what you hold. A new attempt can also save a step you already have, for example when it resumes at the last step: when latestCheckpoint.attempt changes, read checkpoints again from the start, without stepGt, and replace your rows by step.
The run page charts these metrics under Overview and Diagnostics, which has Learning signal, Rollout behavior, and Cost & timing views.
Lists page with limit and cursor: pass nextCursor back as cursor with the same filters and limit until it is null. total is always null, except on listFineTuningJobRolloutGroups, which returns the real count.

Compare against the base model

A baseline scores the base model on the held-out tasks with the settings you will compare against. Create one with steps: 0, then read its summary.evalReward.final. A trained job reports summary.evalReward.base (the score before training) and final (the latest score), so one job already compares against its own base.
Click New run and choose the Baseline (eval only) run type.
To compare two or more runs, read the same metric (for example eval/reward) from each job with listFineTuningJobMetrics. In the console, select two to five runs and click Compare. Compare takes only succeeded runs scored on the same held-out set, so a running run, or a quick run beside a full one, is refused.

Run a long job

Set steps as high as the work needs. An attempt ends after 24 hours and the job usually continues from its latest checkpoint by itself, so a long run needs no babysitting. Its checkpoint interval matters: if checkpointEvery is longer than an attempt, every attempt restarts from the same checkpoint, and three attempts in a row that end without a newer checkpoint fail the job. Keep checkpointEvery well under the steps one attempt can finish. To stop a run when it stops improving, set earlyStopPatience: the run ends successfully once that many held-out checks in a row fail to beat the best score by earlyStopMinDelta. It saves a checkpoint at the step where it stopped, and that checkpoint is the job’s tunedModel. Early stop is off by default.

Cancel and resume

Cancel moves a queued or running job to cancelled. A running attempt is stopped and every saved checkpoint is kept. A cancelled job is returned unchanged, and a succeeded or failed job answers 409 conflict. Idempotency-Key is optional; send one so a retry that lands after a resume cannot cancel the resumed run.
Open the run and click Cancel run.
Resume starts the next attempt of a failed or cancelled job from its latest checkpoint, optimizer state included, or from the beginning when it saved none. The job is running again and keeps its earlier checkpoints; its metric points and rollouts from the resume step on are deleted for the new attempt to write again.
Open the cancelled or failed run and click Resume run.
A queued or running job is returned unchanged and a succeeded job answers 409 conflict. If the last run is still being stopped, the answer is 409 fine_tuning_job_stopping: retry in a minute. Resume is not safe to retry blindly: a retry after the resumed run has settled starts another attempt, which adds training cost, so read the job first.

Read the result

When the job succeeds, result holds the tuned model and the end reason, and summary the scores and cost.
The run page shows the final scores, cost, and the tuned model once the run succeeds.

Cost

While a run works, the cost/total_usd metric is the live estimate. After the job settles, summary.billedCostStatus tells you how far to trust billedCostUsd: pending means the cost is still being worked out and can change, so read the job again later and use estimatedCostUsd meanwhile; final means the amount will not change unless you resume the job: a resume clears it, and the resumed run’s settlement covers every attempt; unavailable means no reliable cost could be determined and billedCostReason says why. The amount is a usage estimate for the run, not a bill.

Use a tuned model in an agent

Every saved checkpoint is a model you can run, not only the last one. List the checkpoints, then copy a checkpoint’s tunedModel into an agent.
The run page lists the checkpoints; each row has a Use in agent button.
Use the tunedModel value as the agent’s model (shown here as tuned/<checkpointId>; copy the one your job returns), as you would a base model id; see Agent setup and the cookbook. The model list shows the final checkpoint of your 20 most recent succeeded jobs under each job’s name, so renaming a job renames its listed model; any other checkpoint can be run by its id. Treat the id as opaque: copy it, do not build it. Rename a job at any time, whatever its status:
On the run’s page, click Rename, edit the name, and click Save.

How a run works

The dataset is a fixed set of 600 scored automation tasks, split with a fixed seed into 480 train and 120 held-out tasks. quick means the 8 easiest train tasks or the 10 easiest held-out tasks; full means every task of the split, cycling through the train tasks. A job is queued until its compute is created, running while any attempt works, then ends succeeded, failed, or cancelled. Within running, progress.phase says what it is doing: queued (also between attempts), provisioning, installing, setup, sampling, training, eval, checkpoint, or finalizing. On the first attempt, provisioning is reported while the status is still queued.

Limits

At most four jobs of an organization hold a compute at once; the rest wait, and a job between attempts takes a free slot before a job that has not started. An attempt lasts 24 hours at most. See Limits for every bound.

Find the right operation

openFineTuningAnalyst is the console’s Ask AI button on a run’s page. It works like the session analyst: each question adds billed usage, so do not retry it blindly. Idempotency: createFineTuningJob requires Idempotency-Key; cancelFineTuningJob accepts one; renaming is safe to repeat; read the job before retrying a resume. Operation ids and every field are in Endpoints. See API conventions for authentication, pagination, and rate limits, and Errors for the codes.

What can go wrong

  • 400 invalid_request on every call. Fine-tuning is not enabled for the organization.
  • 400 on create naming a setting. The setting is outside its bound; the message names it and the allowed range.
  • A run is running but nothing moves. Check progress.lastEventAt and the timeline; see Troubleshooting.
  • 409 fine_tuning_job_stopping on resume. The last run is still stopping; retry in a minute.

Next steps

Fine-tuning cookbook

Run a task, tune the model, run it again, and compare.

Fine-tuning reference

Settings, states, events, metrics, and paging rules.

Agent setup

Run a tuned model in an agent.

Limits

Every fine-tuning bound.

Errors

Every fine-tuning error code.