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 readRECURSION_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.- Console
- cURL
- CLI
- TypeScript
- In the sidebar, open Advanced, then Fine-tuning, and click New run.
- Under Run, optionally set a Name, and choose the Model and the Run type.
- Under Tasks, choose the Train set and Eval set; the dataset is fixed. Under Length, set Training steps.
- Open Customize for the other settings, grouped as Training, Evaluation, Stopping and checkpoints, Compute, and Limits, then click Start run.
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.
Settings and their defaults
Settings and their defaults
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.- Console
- cURL
- CLI
- TypeScript
Open Advanced, then Fine-tuning, then the run. The page shows the phase, the rollouts of the current step, metric charts, checkpoints, and cost.
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.
- Console
- cURL
- CLI
- TypeScript
The run page charts these metrics under Overview and Diagnostics, which has Learning signal, Rollout behavior, and Cost & timing views.
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 withsteps: 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.
- Console
- cURL
- CLI
- TypeScript
Click New run and choose the Baseline (eval only) run type.
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
Setsteps 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 tocancelled. 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.
- Console
- cURL
- CLI
- TypeScript
Open the run and click Cancel run.
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.
- Console
- cURL
- CLI
- TypeScript
Open the cancelled or failed run and click Resume run.
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.
- Console
- cURL
- CLI
- TypeScript
The run page shows the final scores, cost, and the tuned model once the run succeeds.
Result and summary fields
Result and summary fields
Cost
While a run works, thecost/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’stunedModel into an agent.
- Console
- cURL
- CLI
- TypeScript
The run page lists the checkpoints; each row has a Use in agent button.
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:
- Console
- cURL
- CLI
- TypeScript
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_requeston every call. Fine-tuning is not enabled for the organization.400on create naming a setting. The setting is outside its bound; the message names it and the allowed range.- A run is
runningbut nothing moves. Checkprogress.lastEventAtand the timeline; see Troubleshooting. 409 fine_tuning_job_stoppingon 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.