API reference

Fine-tunes

A fine-tune is a supervised training job on a base model, run at the provider and tracked by LoopLlama. When it succeeds, its fine_tuned_model id is usable as any agent's model in the owning account.

Read the Model training guide for data formats, pricing and when to fine-tune. All endpoints require a Bearer API key; creating and cancelling require the Member role.

The fine-tune object#

json

{
  "id": "clx…",
  "name": "Submission classifier",
  "provider": "openai",
  "provider_label": "OpenAI",
  "base_model": "gpt-4.1-mini",
  "base_model_label": "GPT-4.1 mini",
  "suffix": "classifier",
  "status": "succeeded",
  "provider_status": "succeeded",
  "source": "runs",
  "source_workflow_id": "clw…",
  "source_role": "classifier",
  "example_count": 412,
  "training_bytes": 318204,
  "hyperparameters": { "epochs": 3 },
  "provider_job_id": "ftjob-…",
  "fine_tuned_model": "ft:gpt-4.1-mini-2025-04-14:acme:classifier:abc123",
  "trained_tokens": 236910,
  "cost_usd": 1.184550,
  "inference_rate": { "in": 0.8, "out": 3.2 },
  "training_rate": 5,
  "error": null,
  "created_at": "2026-10-05T14:02:11.000Z",
  "started_at": "2026-10-05T14:02:40.000Z",
  "finished_at": "2026-10-05T14:41:03.000Z",
  "last_synced_at": "2026-10-05T14:41:03.000Z"
}

statusstringoptional

queued · validating · running · succeeded · failed · cancelled. Refreshed from the provider on every read and once a minute in the background.

fine_tuned_modelstring | nulloptional

The provider's model id, set when status is succeeded. Use it as a workflow or agent model.

trained_tokensinteger | nulloptional

Tokens the provider reports training on; what the training cost is computed from.

cost_usdnumberoptional

Training cost at the provider's list training rate. Zero until the job succeeds.

inference_rateobject | nulloptional

USD per 1M input/output tokens the fine-tuned model is billed at.

errorstring | nulloptional

The provider's failure message, when status is failed.

Create a fine-tune#

POST/v1/fine-tunes

namestringrequired

Label shown in the dashboard and model pickers (≤ 80 chars).

base_modelstringrequired

A fine-tunable catalog id: gpt-4.1, gpt-4.1-mini, mistral-small-latest, codestral-latest.

source"upload" | "runs"required

Where the examples come from.

training_datastringoptional

source: "upload" — the JSONL text (≤ 20 MB, ≥ 10 examples). Chat-format messages or {"input","output"} lines.

workflow_idstringoptional

source: "runs" — the workflow whose completed run steps become examples.

rolestringoptional

source: "runs" — restrict to one agent role's steps (recommended).

suffixstringoptional

Up to 18 letters, numbers or hyphens, embedded in the provider's model id.

hyperparametersobjectoptional

epochs (OpenAI), training_steps and learning_rate (Mistral). Omit for provider defaults.

Returns 201 with the job. The training set is validated and uploaded before the response, so a bad file is a 400 with the offending line; a provider rejection after upload is recorded on the job as failed with its message. 503 means the base model's provider isn't configured on this deployment.

bash

curl -X POST https://loopllama.ai/api/v1/fine-tunes \
  -H "Authorization: Bearer $LOOPLLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Submission classifier","base_model":"gpt-4.1-mini","source":"runs","workflow_id":"clw…","role":"classifier"}'

List fine-tunes#

GET/v1/fine-tunes

The account's 100 most recent jobs, newest first, as { data: [...] }.

Retrieve a fine-tune#

GET/v1/fine-tunes/:id

Poll this until status is terminal. The SDK's fineTunes.poll(id) does so for you.

Job events#

GET/v1/fine-tunes/:id/events

The provider's event log for the job — validation messages and training progress — as { data: [{ at, level, message }] }, oldest first.

Cancel a fine-tune#

POST/v1/fine-tunes/:id/cancel

Stops an active job at the provider. Nothing is billed for a cancelled job. Terminal jobs are returned unchanged.

Delete a fine-tune#

DELETE/v1/fine-tunes/:id

Cancels the job if it is still active, then removes the record. Its model id is no longer accepted on your workflows. Returns { "data": { "id": "…", "deleted": true } }.

Using the model

Pass fine_tuned_model as a workflow's model or an agent's model on POST /v1/workflows. Ids from other accounts are rejected with 400.