> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fine-tuning

> Train a model on your tasks with reinforcement learning, follow the run, resume or cancel it, and run the tuned model in an agent.

> [!WARNING]
>
> **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.

> [!NOTE]
>
> 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](https://docs.labelbox.com/recursion/api-keys.md). For the full end-to-end loop, see the [Fine-tuning cookbook](https://docs.labelbox.com/recursion/fine-tuning-cookbook.md).

## 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](https://docs.labelbox.com/recursion/api.md#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.

> [tab] Console
>
> 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**.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -H 'Idempotency-Key: risk-triage-run-1' \
>   -d '{"model":"thinkingmachines/Inkling-2-Small","dataset":"automationbench-public-600","name":"Risk triage v1","settings":{"steps":40,"checkpointEvery":10,"evalEvery":5}}'
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents create-fine-tuning-job --input-stdin <<'JSON'
> {"Idempotency-Key":"risk-triage-run-1","body":{"model":"thinkingmachines/Inkling-2-Small","dataset":"automationbench-public-600","name":"Risk triage v1","settings":{"steps":40,"checkpointEvery":10,"evalEvery":5}}}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.createFineTuningJob({
>   "Idempotency-Key": "risk-triage-run-1",
>   body: {
>     model: "thinkingmachines/Inkling-2-Small",
>     dataset: "automationbench-public-600",
>     name: "Risk triage v1",
>     settings: {
>       steps: 40,
>       checkpointEvery: 10,
>       evalEvery: 5,
>     },
>   },
> });
> if (error !== undefined) throw new Error(error.message);
> ```

The response is `201 Created` with the queued job. Keep `jobId`.

```json theme={"theme":"css-variables"}
{
  "jobId": "7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47",
  "name": "Risk triage v1",
  "status": "queued",
  "model": "thinkingmachines/Inkling-2-Small",
  "dataset": "automationbench-public-600",
  "attempt": 1,
  "progress": {"phase": "queued", "step": null, "split": null},
  "result": {"tunedModel": null, "endReason": null},
  "createdAt": "2026-11-21T14:02:11Z"
}
```

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

> [accordion] Settings and their defaults
>
> | Setting | Default | Bounds |
> | - | - | - |
> | `steps` | 2 | 0 to 2147483647. 0 is a baseline. |
> | `groupsPerBatch` | 4 | 1 to 32 |
> | `groupSize` | 4 | 2 to 16 |
> | `learningRate` | 0.00004 | 1e-7 to 0.001 |
> | `loraRank` | 32 | 8, 16, 32, or 64 |
> | `contextLength` | the model's maximum, 262144 | 256 to 262144 |
> | `trainSet`, `evalSet` | `quick` | `quick` or `full` |
> | `evalEvery` | 1 | 1 to `steps` (1 for a baseline) |
> | `evalAttempts` | 4 | 1 to 16 |
> | `evalTasks` | none: use `evalSet` | 1 to 120 |
> | `checkpointEvery` | 10 steps | 1 to 2147483647 |
> | `earlyStopPatience` | none: never stop early | 1 to 2147483647. A baseline refuses it. |
> | `earlyStopMinDelta` | 0 | 0 to 1, only with `earlyStopPatience` |
> | `vcpus` | 8 | 1 to 56; a deployment may admit fewer, and a larger value is refused with an error that names the limit |
> | `maxInFlightRollouts` | 256 | 2 to 4096, at least one whole group |
> | `samplingStepsAhead` | 0 (on-policy) | 0 to 8; a baseline accepts only 0 |
> | `sampleTimeoutMinutes` | 30 | 1 or more |
> | `rolloutTimeoutMinutes` | 240 | 1 or more |
>
> 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](https://docs.labelbox.com/recursion/fine-tuning-reference.md#settings) 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.

> [tab] Console
>
> Open **Advanced**, then **Fine-tuning**, then the run. The page shows the phase, the rollouts of the current step, metric charts, checkpoints, and cost.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs/7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents get-fine-tuning-job --input-stdin <<'JSON'
> {"jobId":"7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47"}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.getFineTuningJob({
>   jobId: "7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47",
> });
> if (error !== undefined) throw new Error(error.message);
> ```

Stop polling when `status` is `succeeded`, `failed`, or `cancelled`. A running job whose `progress.lastEventAt` is long past is stalled; see [Troubleshooting](https://docs.labelbox.com/recursion/troubleshooting.md#fine-tuning).

Each collection can be followed without rereading it. Pass what you last read:

| Collection | Operation | Follow with |
| - | - | - |
| Timeline | `listFineTuningJobEvents` | `seqGt`: the largest `seq` you read |
| Metrics | `listFineTuningJobMetrics` | `stepGte`: the step of the last held-out (`eval/`) point you read, and `name` to pick metrics. Held-out points arrive in step order but can land after the training points of later steps; or follow `train/` and `eval/` names in separate calls, each from its own last step |
| Rollouts | `listFineTuningJobRollouts` | `updatedAtGte`: the largest `updatedAt` you read |
| Checkpoints | `listFineTuningJobCheckpoints` | `stepGt`: the largest `step` you 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`.

> [tab] Console
>
> The run page charts these metrics under **Overview** and **Diagnostics**, which has **Learning signal**, **Rollout behavior**, and **Cost & timing** views.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs/7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47/metrics?name=train/reward&name=eval/reward&stepGte=0' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents list-fine-tuning-job-metrics --input-stdin <<'JSON'
> {"jobId":"7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47","name":["train/reward","eval/reward"],"stepGte":0}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.listFineTuningJobMetrics({
>   jobId: "7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47",
>   name: ["train/reward", "eval/reward"],
>   stepGte: 0,
> });
> if (error !== undefined) throw new Error(error.message);
> ```

```json theme={"theme":"css-variables"}
{
  "items": [
    {"step": 0, "name": "eval/reward", "value": 0.31},
    {"step": 1, "name": "train/reward", "value": 0.34}
  ],
  "nextCursor": null,
  "total": null
}
```

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.

> [tab] Console
>
> Click **New run** and choose the **Baseline (eval only)** run type.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -H 'Idempotency-Key: risk-triage-baseline-1' \
>   -d '{"model":"thinkingmachines/Inkling-2-Small","dataset":"automationbench-public-600","name":"Baseline","settings":{"steps":0,"evalSet":"quick","evalAttempts":4}}'
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents create-fine-tuning-job --input-stdin <<'JSON'
> {"Idempotency-Key":"risk-triage-baseline-1","body":{"model":"thinkingmachines/Inkling-2-Small","dataset":"automationbench-public-600","name":"Baseline","settings":{"steps":0,"evalSet":"quick","evalAttempts":4}}}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.createFineTuningJob({
>   "Idempotency-Key": "risk-triage-baseline-1",
>   body: {
>     model: "thinkingmachines/Inkling-2-Small",
>     dataset: "automationbench-public-600",
>     name: "Baseline",
>     settings: {
>       steps: 0,
>       evalSet: "quick",
>       evalAttempts: 4,
>     },
>   },
> });
> if (error !== undefined) throw new Error(error.message);
> ```

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.

> [tab] Console
>
> Open the run and click **Cancel run**.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs/7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47/cancel' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H 'Idempotency-Key: cancel-triage-run-1'
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents cancel-fine-tuning-job --input-stdin <<'JSON'
> {"jobId":"7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47","Idempotency-Key":"cancel-triage-run-1"}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.cancelFineTuningJob({
>   jobId: "7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47",
>   "Idempotency-Key": "cancel-triage-run-1",
> });
> if (error !== undefined) throw new Error(error.message);
> ```

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.

> [tab] Console
>
> Open the cancelled or failed run and click **Resume run**.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs/7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47/resume' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents resume-fine-tuning-job --input-stdin <<'JSON'
> {"jobId":"7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47"}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.resumeFineTuningJob({
>   jobId: "7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47",
> });
> if (error !== undefined) throw new Error(error.message);
> ```

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.

> [tab] Console
>
> The run page shows the final scores, cost, and the tuned model once the run succeeds.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs/7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents get-fine-tuning-job --input-stdin <<'JSON'
> {"jobId":"7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47"}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.getFineTuningJob({
>   jobId: "7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47",
> });
> if (error !== undefined) throw new Error(error.message);
> ```

> [accordion] Result and summary fields
>
> | Field | Meaning |
> | - | - |
> | `result.endReason` | `steps_completed`, `early_stop`, `cancelled`, or `failed`; `null` while the job is queued or running. |
> | `result.tunedModel` | The model id an agent selects to run the final weights. `null` for a baseline. |
> | `summary.evalReward.base`, `final` | The held-out reward before training and at the latest check. |
> | `summary.evalReward.finalCompleted`, `finalTotal`, `finalNote` | How many attempts of the final check were graded out of how many ran. Failed attempts are left out of `final`, not scored zero, and `finalNote` warns when the check is incomplete. |
> | `failure.reason`, `failure.exitCode` | Why a failed job failed. |
> | `summary.billedCostUsd`, `billedCostStatus`, `estimatedCostUsd` | What the run cost; see below. |

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

> [tab] Console
>
> The run page lists the checkpoints; each row has a **Use in agent** button.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs/7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47/checkpoints' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents list-fine-tuning-job-checkpoints --input-stdin <<'JSON'
> {"jobId":"7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47"}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.listFineTuningJobCheckpoints({
>   jobId: "7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47",
> });
> if (error !== undefined) throw new Error(error.message);
> ```

```json theme={"theme":"css-variables"}
{
  "items": [
    {
      "checkpointId": "<checkpointId>",
      "step": 2,
      "attempt": 1,
      "savedAt": "2026-11-21T14:27:52Z",
      "tunedModel": "tuned/<checkpointId>"
    }
  ],
  "nextCursor": null,
  "total": null
}
```

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](https://docs.labelbox.com/recursion/agents.md) and the [cookbook](https://docs.labelbox.com/recursion/fine-tuning-cookbook.md#3-run-the-same-task-on-the-tuned-checkpoint). 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:

> [tab] Console
>
> On the run's page, click **Rename**, edit the name, and click **Save**.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -X PATCH 'https://api.recursion.labelbox.com/managed-agents/v2/fine-tuning-jobs/7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -d '{"name":"Risk triage v1 (final)"}'
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents update-fine-tuning-job --input-stdin <<'JSON'
> {"jobId":"7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47","body":{"name":"Risk triage v1 (final)"}}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> const { data, error } = await recursion.managedAgents.updateFineTuningJob({
>   jobId: "7c1f4a92-3b58-4e0d-9a16-d2b5e8f03c47",
>   body: {
>     name: "Risk triage v1 (final)",
>   },
> });
> if (error !== undefined) throw new Error(error.message);
> ```

## How a run works

| Concept | Meaning |
| - | - |
| **Job** | One fine-tuning run: a base model, a dataset, settings, and everything it produces. Its `jobId` never changes. |
| **Step** | One training update. Each step samples `groupsPerBatch` tasks, runs `groupSize` rollouts of each, and trains on how their rewards differ inside a group. |
| **Rollout** | One attempt by the model at one task, scored with a reward from 0 to 1. A group is the rollouts of one task in one step. |
| **Held-out check (eval)** | The model run on tasks it never trains on, before the first step, every `evalEvery` steps, and after the last step, giving `eval/reward` and pass rates. The first one, before any training, is the base score; the last one gives `summary.evalReward.final`. |
| **Checkpoint** | The weights after a step, saved every `checkpointEvery` steps and after the last. A checkpoint is what a resumed run continues from and what you run as a tuned model. |
| **Attempt** | One stretch of work. An attempt ends after 24 hours, when it crashes or its compute stops, or when it makes no progress for about 40 minutes (longer when `sampleTimeoutMinutes` is over 30), and the job usually continues by itself from its latest checkpoint as the next attempt, so a long run is several attempts. An attempt that cannot start, ends without a valid result, or stops responding to the platform for more than a day fails the job at once. |
| **Resume** | Starting the next attempt of a failed or cancelled job from its latest checkpoint. Attempts that end by themselves are continued automatically; `resume` is for a job that settled. |
| **End reason** | Why a job reached its final status: `steps_completed`, `early_stop`, `cancelled`, or `failed`. |
| **Baseline** | A job with `steps: 0`. It trains nothing and saves no checkpoint; it only scores the base model on the held-out tasks. |

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](https://docs.labelbox.com/recursion/limits.md#fine-tuning) for every bound.

## Find the right operation

| To | Operation | CLI command |
| - | - | - |
| Start a run or a baseline | `createFineTuningJob` | `create-fine-tuning-job` |
| List runs, newest first | `listFineTuningJobs` | `list-fine-tuning-jobs` |
| Read one run's status and scores | `getFineTuningJob` | `get-fine-tuning-job` |
| Rename a run | `updateFineTuningJob` | `update-fine-tuning-job` |
| Stop a run | `cancelFineTuningJob` | `cancel-fine-tuning-job` |
| Continue a failed or cancelled run | `resumeFineTuningJob` | `resume-fine-tuning-job` |
| Chart a run | `listFineTuningJobMetrics` | `list-fine-tuning-job-metrics` |
| See the timeline of phases, steps, checkpoints, attempts | `listFineTuningJobEvents` | `list-fine-tuning-job-events` |
| Inspect individual rollouts | `listFineTuningJobRollouts` | `list-fine-tuning-job-rollouts` |
| Inspect one step's task groups, filtered and sorted | `listFineTuningJobRolloutGroups` | `list-fine-tuning-job-rollout-groups` |
| Get models to run | `listFineTuningJobCheckpoints` | `list-fine-tuning-job-checkpoints` |
| Ask questions about a run | `openFineTuningAnalyst` | `open-fine-tuning-analyst` |

`openFineTuningAnalyst` is the console's **Ask AI** button on a run's page. It works like the [session analyst](https://docs.labelbox.com/recursion/session-operations.md#ask-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](https://docs.labelbox.com/recursion/api.md) for authentication, pagination, and rate limits, and [Errors](https://docs.labelbox.com/recursion/errors.md#fine-tuning) 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](https://docs.labelbox.com/recursion/troubleshooting.md#fine-tuning).
* **`409 fine_tuning_job_stopping` on resume.** The last run is still stopping; retry in a minute.

## Next steps

> [card] [Fine-tuning cookbook](https://docs.labelbox.com/recursion/fine-tuning-cookbook.md)
>
> Run a task, tune the model, run it again, and compare.

> [card] [Fine-tuning reference](https://docs.labelbox.com/recursion/fine-tuning-reference.md)
>
> Settings, states, events, metrics, and paging rules.

> [card] [Agent setup](https://docs.labelbox.com/recursion/agents.md)
>
> Run a tuned model in an agent.

> [card] [Limits](https://docs.labelbox.com/recursion/limits.md#fine-tuning)
>
> Every fine-tuning bound.

> [card] [Errors](https://docs.labelbox.com/recursion/errors.md#fine-tuning)
>
> Every fine-tuning error code.
