Fine-Tuning

Create, manage, and monitor fine-tuning jobs for large language models. Fine-tuning allows you to customize a base model on your own training data to improve performance for specific tasks.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

FineTuningJob Object

{
  "id": "ftjob_abc123",
  "name": "Customer Support Classifier",
  "baseModel": "llama-3.1-8b",
  "status": "running",
  "description": "Fine-tuned on 10k support tickets for intent classification",
  "owner": "user_456",
  "organizationId": "org_xyz",
  "trainingDataset": "ds_train_001",
  "trainingFile": "training_data.jsonl",
  "validationFile": "validation_data.jsonl",
  "hyperparameters": {
    "epochs": 3,
    "learningRate": 0.0002,
    "batchSize": 8,
    "warmupSteps": 100
  },
  "resultModel": null,
  "trainedTokens": 1250000,
  "error": null,
  "metrics": {
    "trainingLoss": 0.342,
    "validationLoss": 0.389,
    "epoch": 2
  },
  "startedAt": "2025-02-01T10:00:00Z",
  "finishedAt": null,
  "createdAt": "2025-02-01T09:55:00Z",
  "updatedAt": "2025-02-01T12:30:00Z"
}

---

GET /api/v1/fine-tuning/jobs

List all fine-tuning jobs accessible to the authenticated user.

Scope: fine-tuning:read

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: queued, running, completed, failed, stopped
baseModel	string	No	Filter by base model name
search	string	No	Search by job name or description
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)
sort	string	No	Sort field and direction, e.g. createdAt:desc

Response 200 OK

{
  "count": 15,
  "limit": 20,
  "offset": 0,
  "jobs": [
    {
      "id": "ftjob_abc123",
      "name": "Customer Support Classifier",
      "baseModel": "llama-3.1-8b",
      "status": "running",
      "description": "Fine-tuned on 10k support tickets for intent classification",
      "owner": "user_456",
      "organizationId": "org_xyz",
      "trainedTokens": 1250000,
      "startedAt": "2025-02-01T10:00:00Z",
      "finishedAt": null,
      "createdAt": "2025-02-01T09:55:00Z",
      "updatedAt": "2025-02-01T12:30:00Z"
    }
  ]
}

---

POST /api/v1/fine-tuning/jobs

Create a new fine-tuning job.

Scope: fine-tuning:write

Request Body

{
  "name": "Customer Support Classifier",
  "baseModel": "llama-3.1-8b",
  "trainingDataset": "ds_train_001",
  "description": "Fine-tuned on 10k support tickets for intent classification",
  "validationFile": "validation_data.jsonl",
  "hyperparameters": {
    "epochs": 3,
    "learningRate": 0.0002,
    "batchSize": 8,
    "warmupSteps": 100
  },
  "suffix": "support-v1"
}

Field	Type	Required	Description
name	string	Yes	Human-readable job name
baseModel	string	Yes	Base model to fine-tune (e.g. llama-3.1-8b)
trainingDataset	string	Yes	ID or path of the training dataset
description	string	No	Job description
validationFile	string	No	Validation dataset file for evaluation during training
hyperparameters	object	No	Training hyperparameters (epochs, learningRate, batchSize, warmupSteps)
suffix	string	No	Suffix to append to the resulting model name

Response 201 Created

{
  "id": "ftjob_abc123",
  "name": "Customer Support Classifier",
  "baseModel": "llama-3.1-8b",
  "status": "queued",
  "createdAt": "2025-02-01T09:55:00Z"
}

---

GET /api/v1/fine-tuning/jobs/:id

Get a single fine-tuning job by ID.

Scope: fine-tuning:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Fine-tuning job ID

Response 200 OK

Returns the full FineTuningJob object.

---

DELETE /api/v1/fine-tuning/jobs/:id

Delete a fine-tuning job. Running jobs must be stopped before deletion.

Scope: fine-tuning:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Fine-tuning job ID

Response 204 No Content

---

POST /api/v1/fine-tuning/jobs/:id/stop

Stop a running fine-tuning job. The job will be marked as stopped and training will be terminated.

Scope: fine-tuning:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Fine-tuning job ID

Response 200 OK

{
  "id": "ftjob_abc123",
  "status": "stopped",
  "message": "Fine-tuning job stopped successfully"
}

---

POST /api/v1/fine-tuning/jobs/:id/restart

Restart a stopped or failed fine-tuning job. The job will be re-queued for execution.

Scope: fine-tuning:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Fine-tuning job ID

Response 200 OK

{
  "id": "ftjob_abc123",
  "status": "queued",
  "message": "Fine-tuning job restarted successfully"
}

---

POST /api/v1/fine-tuning/jobs/:id/deploy

Deploy the resulting model from a completed fine-tuning job. Makes the fine-tuned model available for inference.

Scope: fine-tuning:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Fine-tuning job ID

Response 200 OK

{
  "id": "ftjob_abc123",
  "resultModel": "llama-3.1-8b-support-v1",
  "status": "deployed",
  "message": "Fine-tuned model deployed successfully"
}

---

GET /api/v1/fine-tuning/jobs/:id/logs

Retrieve training logs for a fine-tuning job.

Scope: fine-tuning:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Fine-tuning job ID

Query Parameters

Parameter	Type	Required	Description
lines	integer	No	Number of log lines to return (default: 100)
since	string	No	Return logs after this ISO 8601 timestamp

Response 200 OK

{
  "jobId": "ftjob_abc123",
  "logs": [
    {
      "timestamp": "2025-02-01T10:00:05Z",
      "level": "info",
      "message": "Training started with 3 epochs"
    },
    {
      "timestamp": "2025-02-01T10:05:30Z",
      "level": "info",
      "message": "Epoch 1/3 completed - loss: 0.542"
    }
  ]
}

---

GET /api/v1/fine-tuning/jobs/:id/metrics

Retrieve training metrics for a fine-tuning job, including loss curves and evaluation results.

Scope: fine-tuning:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Fine-tuning job ID

Response 200 OK

{
  "jobId": "ftjob_abc123",
  "metrics": {
    "trainingLoss": 0.342,
    "validationLoss": 0.389,
    "currentEpoch": 2,
    "totalEpochs": 3,
    "trainedTokens": 1250000,
    "steps": [
      {
        "step": 100,
        "trainingLoss": 0.85,
        "validationLoss": 0.91,
        "learningRate": 0.0002
      },
      {
        "step": 200,
        "trainingLoss": 0.54,
        "validationLoss": 0.62,
        "learningRate": 0.0002
      }
    ]
  }
}

---

GET /api/v1/fine-tuning/stats

Get aggregate statistics for fine-tuning jobs in the organization.

Scope: fine-tuning:read

Response 200 OK

{
  "total": 15,
  "running": 2,
  "completed": 8,
  "failed": 3,
  "queued": 2
}

---

GET /api/v1/fine-tuning/base-models

List available base models that can be used for fine-tuning.

Scope: fine-tuning:read

Response 200 OK

{
  "models": [
    {
      "id": "llama-3.1-8b",
      "name": "LLaMA 3.1 8B",
      "provider": "meta",
      "parameterCount": "8B",
      "supportedTasks": ["text-generation", "classification"],
      "maxSequenceLength": 8192
    },
    {
      "id": "llama-3.1-70b",
      "name": "LLaMA 3.1 70B",
      "provider": "meta",
      "parameterCount": "70B",
      "supportedTasks": ["text-generation", "classification", "summarization"],
      "maxSequenceLength": 8192
    },
    {
      "id": "mistral-7b-v0.3",
      "name": "Mistral 7B v0.3",
      "provider": "mistralai",
      "parameterCount": "7B",
      "supportedTasks": ["text-generation", "classification"],
      "maxSequenceLength": 32768
    }
  ]
}

---

GET /api/v1/fine-tuning/hardware

List available hardware options for fine-tuning jobs.

Scope: fine-tuning:read

Response 200 OK

{
  "hardware": [
    {
      "id": "gpu-a100-40gb",
      "name": "NVIDIA A100 40GB",
      "gpuMemory": "40GB",
      "gpuCount": 1,
      "costPerHour": 3.50
    },
    {
      "id": "gpu-a100-80gb",
      "name": "NVIDIA A100 80GB",
      "gpuMemory": "80GB",
      "gpuCount": 1,
      "costPerHour": 5.00
    },
    {
      "id": "gpu-a100-80gb-x4",
      "name": "NVIDIA A100 80GB x4",
      "gpuMemory": "80GB",
      "gpuCount": 4,
      "costPerHour": 18.00
    }
  ]
}

---

POST /api/v1/fine-tuning/estimate-cost

Estimate the cost and time for a fine-tuning job based on the base model and dataset size.

Scope: fine-tuning:read

Request Body

{
  "baseModel": "llama-3.1-8b",
  "datasetSize": 50000
}

Field	Type	Required	Description
baseModel	string	Yes	Base model ID to estimate cost for
datasetSize	integer	Yes	Number of training examples in the dataset

Response 200 OK

{
  "baseModel": "llama-3.1-8b",
  "datasetSize": 50000,
  "estimatedCost": 42.50,
  "estimatedTimeMinutes": 180,
  "currency": "USD"
}