> This page is for version v2 API (default).
> For other versions, use one of these documentation indexes:
> - v2 API (default): https://docs.cohere.com/v2/llms.txt
> - v1 API: https://docs.cohere.com/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cohere.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cohere.com/_mcp/server.

# Trains and deploys a fine-tuned model.

POST https://api.cohere.com/v1/finetuning/finetuned-models
Content-Type: application/json

Creates a new fine-tuned model. The model will be trained on the dataset specified in the request body. The training process may take some time, and the model will be available once the training is complete.

Reference: https://docs.cohere.com/reference/createfinetunedmodel

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Headers

- `X-Client-Name` (string, optional) — The name of the project that is making the request.

### Body (application/json)

This endpoint expects a FinetunedModel.

- `name` (string, required) — FinetunedModel name (e.g. `foobar`).
- `settings` (Settings, required) — FinetunedModel settings such as dataset, hyperparameters...
- `id` (string, optional) — read-only. FinetunedModel ID.
- `creator_id` (string, optional) — read-only. User ID of the creator.
- `organization_id` (string, optional) — read-only. Organization ID.
- `status` (enum, optional, default: STATUS_UNSPECIFIED) — read-only. Current stage in the life-cycle of the fine-tuned model.
  - Allowed values: `STATUS_UNSPECIFIED`, `STATUS_FINETUNING`, `STATUS_DEPLOYING_API`, `STATUS_READY`, `STATUS_FAILED`, `STATUS_DELETED`, `STATUS_TEMPORARILY_OFFLINE`, `STATUS_PAUSED`, `STATUS_QUEUED`
- `created_at` (string, optional) — read-only. Creation timestamp.
- `updated_at` (string, optional) — read-only. Latest update timestamp.
- `completed_at` (string, optional) — read-only. Timestamp for the completed fine-tuning.
- `last_used` (string, optional) — read-only. Deprecated: Timestamp for the latest request to this fine-tuned model.

## Response

### 200

A successful response.

- `finetuned_model` (FinetunedModel, optional) — Information about the fine-tuned model.

## Errors

### 400 Bad Request Error

Bad Request

- `message` (string, optional) — A developer-facing error message.

### 401 Unauthorized Error

Unauthorized

- `message` (string, optional) — A developer-facing error message.

### 403 Forbidden Error

Forbidden

- `message` (string, optional) — A developer-facing error message.

### 404 Not Found Error

Not Found

- `message` (string, optional) — A developer-facing error message.

### 500 Internal Server Error

Internal Server Error

- `message` (string, optional) — A developer-facing error message.

### 503 Service Unavailable Error

Status Service Unavailable

- `message` (string, optional) — A developer-facing error message.

## Types

### Settings

The configuration used for fine-tuning.

- `base_model` (BaseModel, required) — The base model to fine-tune.
- `dataset_id` (string, required) — The data used for training and evaluating the fine-tuned model.
- `hyperparameters` (Hyperparameters, optional) — Fine-tuning hyper-parameters.
- `multi_label` (boolean, optional) — read-only. Whether the model is single-label or multi-label (only for classification).
- `wandb` (WandbConfig, optional) — The Weights & Biases configuration (Chat fine-tuning only).

### FinetunedModel

This resource represents a fine-tuned model.

- `name` (string, required) — FinetunedModel name (e.g. `foobar`).
- `settings` (Settings, required) — FinetunedModel settings such as dataset, hyperparameters...
- `id` (string, optional) — read-only. FinetunedModel ID.
- `creator_id` (string, optional) — read-only. User ID of the creator.
- `organization_id` (string, optional) — read-only. Organization ID.
- `status` (enum, optional, default: STATUS_UNSPECIFIED) — read-only. Current stage in the life-cycle of the fine-tuned model.
  - Allowed values: `STATUS_UNSPECIFIED`, `STATUS_FINETUNING`, `STATUS_DEPLOYING_API`, `STATUS_READY`, `STATUS_FAILED`, `STATUS_DELETED`, `STATUS_TEMPORARILY_OFFLINE`, `STATUS_PAUSED`, `STATUS_QUEUED`
- `created_at` (string, optional) — read-only. Creation timestamp.
- `updated_at` (string, optional) — read-only. Latest update timestamp.
- `completed_at` (string, optional) — read-only. Timestamp for the completed fine-tuning.
- `last_used` (string, optional) — read-only. Deprecated: Timestamp for the latest request to this fine-tuned model.

### BaseModel

The base model used for fine-tuning.

- `base_type` (enum, required, default: BASE_TYPE_UNSPECIFIED) — The type of the base model.
  - Allowed values: `BASE_TYPE_UNSPECIFIED`, `BASE_TYPE_GENERATIVE`, `BASE_TYPE_CLASSIFICATION`, `BASE_TYPE_RERANK`, `BASE_TYPE_CHAT`
- `name` (string, optional) — The name of the base model.
- `version` (string, optional) — read-only. The version of the base model.
- `strategy` (enum, optional, default: STRATEGY_UNSPECIFIED) — Deprecated: The fine-tuning strategy.
  - Allowed values: `STRATEGY_UNSPECIFIED`, `STRATEGY_VANILLA`, `STRATEGY_TFEW`

### Hyperparameters

The fine-tuning hyperparameters.

- `early_stopping_patience` (integer, optional) — Stops training if the loss metric does not improve beyond the value of `early_stopping_threshold` after this many times of evaluation.
- `early_stopping_threshold` (double, optional) — How much the loss must improve to prevent early stopping.
- `train_batch_size` (integer, optional) — The batch size is the number of training examples included in a single training pass.
- `train_epochs` (integer, optional) — The number of epochs to train for.
- `learning_rate` (double, optional) — The learning rate to be used during training.
- `lora_alpha` (integer, optional) — Controls the scaling factor for LoRA updates. Higher values make the updates more impactful.
- `lora_rank` (integer, optional) — Specifies the rank for low-rank matrices. Lower ranks reduce parameters but may limit model flexibility.
- `lora_target_modules` (enum, optional, default: LORA_TARGET_MODULES_UNSPECIFIED) — The combination of LoRA modules to target.
  - Allowed values: `LORA_TARGET_MODULES_UNSPECIFIED`, `LORA_TARGET_MODULES_QV`, `LORA_TARGET_MODULES_QKVO`, `LORA_TARGET_MODULES_QKVO_FFN`

### WandbConfig

The Weights & Biases configuration.

- `project` (string, required) — The WandB project name to be used during training.
- `api_key` (string, required) — The WandB API key to be used during training.
- `entity` (string, optional) — The WandB entity name to be used during training.

## Examples

**Request**

```json
{
  "name": "string",
  "settings": {
    "base_model": {
      "base_type": "BASE_TYPE_UNSPECIFIED"
    },
    "dataset_id": "string"
  }
}
```

**Response**

```json
{
  "finetuned_model": {
    "name": "string",
    "settings": {
      "base_model": {
        "base_type": "BASE_TYPE_UNSPECIFIED",
        "name": "string",
        "version": "string",
        "strategy": "STRATEGY_UNSPECIFIED"
      },
      "dataset_id": "string",
      "hyperparameters": {
        "early_stopping_patience": 1,
        "early_stopping_threshold": 1.1,
        "train_batch_size": 1,
        "train_epochs": 1,
        "learning_rate": 1.1,
        "lora_alpha": 1,
        "lora_rank": 1,
        "lora_target_modules": "LORA_TARGET_MODULES_UNSPECIFIED"
      },
      "multi_label": true,
      "wandb": {
        "project": "string",
        "api_key": "string",
        "entity": "string"
      }
    },
    "id": "string",
    "creator_id": "string",
    "organization_id": "string",
    "status": "STATUS_UNSPECIFIED",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "completed_at": "2024-01-15T09:30:00Z",
    "last_used": "2024-01-15T09:30:00Z"
  }
}
```

**SDK Code**

```java Cohere java SDK
/* (C)2024 */
package finetuning;

import com.cohere.api.Cohere;
import com.cohere.api.resources.finetuning.finetuning.types.*;

public class CreateFinetunedModel {
  public static void main(String[] args) {
    Cohere cohere = Cohere.builder().clientName("snippet").build();

    CreateFinetunedModelResponse response =
        cohere
            .finetuning()
            .createFinetunedModel(
                FinetunedModel.builder()
                    .name("test-finetuned-model")
                    .settings(
                        Settings.builder()
                            .baseModel(
                                BaseModel.builder().baseType(BaseType.BASE_TYPE_CHAT).build())
                            .datasetId("my-dataset-id")
                            .build())
                    .build());

    System.out.println(response);
  }
}

```

```go Cohere Go SDK
package main

import (
	"context"
	"log"
	"os"

	"github.com/cohere-ai/cohere-go/v2/client"
	"github.com/cohere-ai/cohere-go/v2/finetuning"
)

func main() {
	co := client.NewClient(client.WithToken(os.Getenv("CO_API_KEY")))

	resp, err := co.Finetuning.CreateFinetunedModel(
		context.TODO(),
		&finetuning.FinetunedModel{
			Name: "test-finetuned-model",
			Settings: &finetuning.Settings{
				DatasetId: "my-dataset-id",
				BaseModel: &finetuning.BaseModel{
					BaseType: finetuning.BaseTypeBaseTypeChat,
				},
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("%+v", resp.FinetunedModel)
}

```

```typescript Cohere TypeScript SDK
const { Cohere, CohereClient } = require('cohere-ai');

const cohere = new CohereClient({
  token: '<<apiKey>>',
});

(async () => {
  const finetunedModel = await cohere.finetuning.createFinetunedModel({
    name: 'test-finetuned-model',
    settings: {
      base_model: {
        base_type: Cohere.Finetuning.BaseType.BaseTypeChat,
      },
      dataset_id: 'test-dataset-id',
    },
  });

  console.log(finetunedModel);
})();

```

```python Sync
from cohere.finetuning import (
    BaseModel,
    FinetunedModel,
    Hyperparameters,
    Settings,
    WandbConfig,
)
import cohere

co = cohere.Client()
hp = Hyperparameters(
    early_stopping_patience=10,
    early_stopping_threshold=0.001,
    train_batch_size=16,
    train_epochs=1,
    learning_rate=0.01,
)
wnb_config = WandbConfig(
    project="test-project",
    api_key="<<wandbApiKey>>",
    entity="test-entity",
)
finetuned_model = co.finetuning.create_finetuned_model(
    request=FinetunedModel(
        name="test-finetuned-model",
        settings=Settings(
            base_model=BaseModel(
                base_type="BASE_TYPE_CHAT",
            ),
            dataset_id="my-dataset-id",
            hyperparameters=hp,
            wandb=wnb_config,
        ),
    )
)
print(finetuned_model)

```

```python Async
from cohere.finetuning import (
    BaseModel,
    FinetunedModel,
    Settings,
)
import cohere
import asyncio

co = cohere.AsyncClient()


async def main():
    response = await co.finetuning.create_finetuned_model(
        request=FinetunedModel(
            name="test-finetuned-model",
            settings=Settings(
                base_model=BaseModel(
                    base_type="BASE_TYPE_CHAT",
                ),
                dataset_id="my-dataset-id",
            ),
        )
    )
    print(response)


asyncio.run(main())

```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cohere.com/v1/finetuning/finetuned-models")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Client-Name"] = 'my-cool-project'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"string\",\n  \"settings\": {\n    \"base_model\": {\n      \"base_type\": \"BASE_TYPE_UNSPECIFIED\"\n    },\n    \"dataset_id\": \"string\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cohere.com/v1/finetuning/finetuned-models', [
  'body' => '{
  "name": "string",
  "settings": {
    "base_model": {
      "base_type": "BASE_TYPE_UNSPECIFIED"
    },
    "dataset_id": "string"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'X-Client-Name' => 'my-cool-project',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.cohere.com/v1/finetuning/finetuned-models");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Client-Name", "my-cool-project");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"string\",\n  \"settings\": {\n    \"base_model\": {\n      \"base_type\": \"BASE_TYPE_UNSPECIFIED\"\n    },\n    \"dataset_id\": \"string\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Client-Name": "my-cool-project",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "string",
  "settings": [
    "base_model": ["base_type": "BASE_TYPE_UNSPECIFIED"],
    "dataset_id": "string"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cohere.com/v1/finetuning/finetuned-models")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```