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

# Create Fine-tuning Job

> Create a fine-tuning job

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.5](/release-notes/1.1.x#v1-1-5) or later of the Archetype platform.
</Callout>

## Overview

Submits a fine-tuning job for the selected model. The request body varies by `model`; see the
request schema for the per-model methods, hyperparameters, and accepted file formats. Poll the
returned job for its status, using the [Get Job](/api-reference/fine-tuning/get-job) endpoint.

## Request

Describes the new fine-tuning job. The exact shape of the input parameters depends on the `model`
you specify.

<ParamField body="model" type="string" required>
  The base model to fine-tune. One of `newton` or `omega`.
</ParamField>

<ParamField body="name" type="string" required>
  A human-readable name for the fine-tuning job. This is used to identify the job in listings and results.
</ParamField>

<ParamField body="suffix" type="string">
  Optional string which is appended to the name of the resulting fine-tuned model to help tell it apart from other fine-tunes.
</ParamField>

<ParamField body="seed" type="integer">
  Optional random seed controlling reproducibility. The same seed with the same inputs produces
  the same results where possible. Omit this parameter to use a random seed.
</ParamField>

<ParamField body="checkpoint_id" type="string">
  Optional checkpoint (`ckp_...`) to warm-start from; omit to train from the base model. Options
  can be sourced using the [List Checkpoint Options](/api-reference/fine-tuning/list-checkpoint-options) endpoint.
</ParamField>

<ParamField body="method" type="object" required>
  The fine-tuning method to use along with its settings. The available methods depend on the selected `model`.

  <Expandable title="Newton: method.type = lora">
    <ParamField body="type" type="string" required>
      The method type. Must be `lora`, which specifies to use low-rank adaptation (LoRA) fine-tuning.
    </ParamField>

    <ParamField body="lora" type="object">
      Settings for low-rank adaptation (LoRA) fine-tuning.

      <Expandable title="lora.hyperparameters">
        <ParamField body="batch_size" type="integer | string">
          How many training examples are grouped together before the model's weights are updated. Larger batches update the weights less often but make each update steadier. Defaults to `"auto"` to choose an optimal value.
        </ParamField>

        <ParamField body="learning_rate_multiplier" type="number | string">
          Scales the base learning rate. Lower values take smaller, more cautious steps that can help avoid overfitting; higher values learn faster but may become unstable. Defaults to `"auto"` to choose an optimal value.
        </ParamField>

        <ParamField body="n_epochs" type="integer | string">
          How many times the entire training dataset is passed through. More epochs give the model more chances to learn, at the cost of longer training and a greater chance of overfitting. Defaults to `"auto"` to choose an optimal value.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>

  <Expandable title="Omega: method.type = head">
    <ParamField body="type" type="string" required>
      The method type: `head`, for head-only fine-tuning.
    </ParamField>

    <ParamField body="head" type="object">
      Settings for head-only fine-tuning.

      <Expandable title="head.hyperparameters">
        <ParamField body="batch_size" type="integer | string">
          The batch size, indicating how many training examples are grouped together before the model's weights are updated. Defaults to `"auto"` to choose an optimal value.
        </ParamField>

        <ParamField body="n_epochs" type="integer | string">
          How many times the entire training dataset is passed through. Defaults to `"auto"` to choose an optimal value.
        </ParamField>
      </Expandable>

      <Expandable title="head.reader: sliding-window reader for Omega CSV inputs">
        <ParamField body="data_columns" type="array | string">
          Names of the CSV data columns to use as input features, or `"auto"` to use all columns.
        </ParamField>

        <ParamField body="step_size" type="integer | string">
          The number of rows to advance between consecutive windows. `"auto"` lets the worker choose.
        </ParamField>

        <ParamField body="window_size" type="integer | string">
          The window size, specifying the number of consecutive rows in each input window. `"auto"` lets the worker choose.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="training_files" type="array" required>
  The files used to train the model.

  <Expandable title="Newton: plain file">
    <ParamField body="type" type="string" required>
      The file type; must be `plain`, indicating a plain data file.
    </ParamField>

    <ParamField body="file_id" type="string" required>
      The file ID of a previously uploaded file which contains the data.
    </ParamField>

    <ParamField body="format" type="string">
      The file's data format. Newton files must be provided in JSON Lines format (`jsonl`).
    </ParamField>
  </Expandable>

  <Expandable title="Omega: n_shot file">
    <ParamField body="type" type="string" required>
      The file type; must be `n_shot`, indicating the file is an N-shot labelled example file.
    </ParamField>

    <ParamField body="file_id" type="string" required>
      The file ID of a previously uploaded file containing the data.
    </ParamField>

    <ParamField body="label" type="string" required>
      The class label that the examples in this file represent.
    </ParamField>

    <ParamField body="format" type="string">
      The file's data format. Omega files must be provided in CSV format (`csv`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="validation_files" type="array">
  An optional array of files used to evaluate the model during training; metrics on these files help you spot overfitting. Uses the same per-model file shapes as `training_files`.
</ParamField>

## Response

Returns a description of the new fine-tuning job.

<ResponseField name="object" type="string" required>
  The object type. Always `fine_tuning.job`.
</ResponseField>

<ResponseField name="id" type="string" required>
  A unique ID for the fine-tuning job.
</ResponseField>

<ResponseField name="name" type="string" required>
  The human-readable name supplied when the job was created.
</ResponseField>

<ResponseField name="model" type="string" required>
  The base model being fine-tuned.
</ResponseField>

<ResponseField name="created_at" type="integer" required>
  The Unix timestamp (in seconds) at which the job was created.
</ResponseField>

<ResponseField name="org_id" type="string" required>
  The organization that owns the job.
</ResponseField>

<ResponseField name="status" type="string" required>
  The job's current lifecycle stage. Mirrors the underlying Jobs Orchestraation Service job
  status. A job that finished processing is `COMPLETED` regardless of whether some inputs
  failed; inspect `outcome` for that information. One of `PENDING`, `ADMITTED`, `RUNNING`, `COMPLETED`,
  `FAILED`, `PREEMPTED`, `CANCELLED`, `PAUSED`, `INTERRUPTED`.
</ResponseField>

<ResponseField name="training_files" type="array" required>
  An array of file IDs indicating the files used to train the model.
</ResponseField>

<ResponseField name="validation_files" type="array" required>
  An array of file IDs indicating the files used to evaluate the model during training.
</ResponseField>

<ResponseField name="errors" type="array" required>
  When the job has failed, this array describes the error(s) which occurred, as the platform
  error envelope (a list of `{code, message, suggestion, error_uid}`). Empty while the job is
  queued/running or on success. See [Error Handling](/api-reference/errors) for more information
  about handling platform errors.
</ResponseField>

<ResponseField name="checkpoint_id" type="string">
  The checkpoint the job was started from, or `null` if it trained from the base model.
</ResponseField>

<ResponseField name="fine_tuned_model" type="string">
  Name of the finely-tuned model produced by the job, available once training has succeeded; `null` until then.
</ResponseField>

<ResponseField name="finished_at" type="integer">
  The Unix timestamp (in seconds) at which the job finished, or `null` if it is not yet complete.
</ResponseField>

<ResponseField name="outcome" type="string">
  For a `COMPLETED` job, this indicates whether it succeeded fully (`SUCCESS`), partially
  (`PARTIAL`), or produced nothing (`FAILED`). This is `null` for any non-completed status.
</ResponseField>

<ResponseField name="seed" type="integer">
  The random seed used for the job.
</ResponseField>

<ResponseField name="user_provided_suffix" type="string">
  The suffix supplied on the request, applied to the fine-tuned model's name.
</ResponseField>

<RequestExample>
  ```bash cURL - Newton (LoRA) theme={"system"}
  curl -X POST https://api.u1.archetypeai.app/v0.6/fine_tuning/jobs \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "newton",
      "name": "my-tune",
      "suffix": "v2",
      "seed": 42,
      "method": {"type": "lora", "lora": {"hyperparameters": {"n_epochs": 3}}},
      "training_files": [{"type": "plain", "file_id": "fil_..."}],
      "validation_files": [{"type": "plain", "file_id": "fil_..."}]
    }'
  ```

  ```bash cURL - Omega (head) theme={"system"}
  curl -X POST https://api.u1.archetypeai.app/v0.6/fine_tuning/jobs \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "omega",
      "name": "my-tune",
      "method": {"type": "head", "head": {"hyperparameters": {}}},
      "training_files": [{"type": "n_shot", "file_id": "fil_...", "label": "cat"}]
    }'
  ```

  ```python Python theme={"system"}
  import requests
  import os

  api_key = os.environ.get("ATAI_API_KEY")

  response = requests.post(
      "https://api.u1.archetypeai.app/v0.6/fine_tuning/jobs",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      },
      json={
          "model": "newton",
          "name": "my-tune",
          "suffix": "v2",
          "seed": 42,
          "method": {"type": "lora", "lora": {"hyperparameters": {"n_epochs": 3}}},
          "training_files": [{"type": "plain", "file_id": "fil_..."}],
          "validation_files": [{"type": "plain", "file_id": "fil_..."}]
      }
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch('https://api.u1.archetypeai.app/v0.6/fine_tuning/jobs', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'newton',
      name: 'my-tune',
      suffix: 'v2',
      seed: 42,
      method: { type: 'lora', lora: { hyperparameters: { n_epochs: 3 } } },
      training_files: [{ type: 'plain', file_id: 'fil_...' }],
      validation_files: [{ type: 'plain', file_id: 'fil_...' }]
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Fine-tuning job created theme={"system"}
  {
    "object": "fine_tuning.job",
    "id": "your-job-id",
    "name": "my-tune",
    "model": "newton",
    "created_at": 1765201323,
    "org_id": "your-org",
    "status": "PENDING",
    "checkpoint_id": null,
    "fine_tuned_model": null,
    "finished_at": null,
    "outcome": null,
    "seed": 42,
    "user_provided_suffix": "v2",
    "training_files": ["fil_..."],
    "validation_files": ["fil_..."],
    "errors": []
  }
  ```

  ```json 400 - Invalid request theme={"system"}
  {
    "code": "invalid_request",
    "message": "Invalid request",
    "suggestion": null,
    "error_uid": "err-xxxxxxxx"
  }
  ```

  ```json 501 - Model not yet supported theme={"system"}
  {
    "code": "model_not_supported",
    "message": "Model not yet supported",
    "suggestion": null,
    "error_uid": "err-xxxxxxxx"
  }
  ```
</ResponseExample>