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

# List Fine-tuning Jobs

> List fine-tuning jobs (cursor-paginated, newest first)

<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

Returns a cursor-paginated list of fine-tuning jobs, sorted with the newest job first.

## Request

<ParamField query="model" type="string">
  Filter by model, e.g. `newton`.
</ParamField>

<ParamField query="method" type="string">
  Filter by training method, e.g. `lora` or `head`.
</ParamField>

<ParamField query="status" type="string">
  Filter by lifecycle status, e.g. `RUNNING`, `COMPLETED`, `FAILED`. A job that has not been
  dispatched yet is `PENDING`.
</ParamField>

<ParamField query="outcome" type="string">
  Filter by completion outcome (`SUCCESS`/`PARTIAL`/`FAILED`). Only completed jobs carry an
  outcome, so specifying a value for this parameter implicitly limits results to completed jobs.
</ParamField>

<ParamField query="q" type="string">
  Case-insensitive search matched against the job name, suffix, and produced model name.
</ParamField>

<ParamField query="after" type="string">
  Forward cursor: return jobs older than the job with this ID. Pass the ID of the last job from
  the previous page to fetch the next page. Mutually exclusive with `before`.
</ParamField>

<ParamField query="before" type="string">
  Backward cursor: return jobs newer than the job with this ID. Pass the ID of the first job
  from the current page to fetch the previous page. Mutually exclusive with `after`.
</ParamField>

<ParamField query="limit" type="integer">
  The maximum number of jobs to return (1–100).
</ParamField>

## Response

Returns a page of fine-tuning jobs.

<ResponseField name="object" type="string">
  The object type. Always `list`.
</ResponseField>

<ResponseField name="data" type="array">
  An array of the jobs for this page, sorted newest-first. Each item is a fine-tuning job object.

  <Expandable title="Fine-tuning job">
    The description of a single fine-tuning job.

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

    <ResponseField name="id" type="string" required>
      The unique identifier of 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. One of `PENDING`, `ADMITTED`, `RUNNING`, `COMPLETED`, `FAILED`, `PREEMPTED`, `CANCELLED`, `PAUSED`, `INTERRUPTED`.
    </ResponseField>

    <ResponseField name="training_files" type="array" required>
      Identifiers of the training files used to train the model.
    </ResponseField>

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

    <ResponseField name="errors" type="array" required>
      When the job has failed, this array lists the error(s) that occcurred, as the platform error envelope (a list of
      `{code, message, suggestion, error_uid}`). Empty while the job is queued/running or on success.
    </ResponseField>

    <ResponseField name="checkpoint_id" type="string">
      The ID of 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 model produced by the job. This is only available once training has succeeded; until then, this value is `null`.
    </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 value indicates whether it succeeded fully (`SUCCESS`),
      partially (`PARTIAL`), or produced nothing (`FAILED`). For any job that hasn't completed,
      this value is `null`.
    </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>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more jobs exist beyond this page.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl "https://api.u1.archetypeai.app/v0.6/fine_tuning/jobs?model=newton&status=RUNNING&limit=20" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

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

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

  response = requests.get(
      "https://api.u1.archetypeai.app/v0.6/fine_tuning/jobs",
      headers={"Authorization": f"Bearer {api_key}"},
      params={"model": "newton", "status": "RUNNING", "limit": 20}
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={"system"}
  const params = new URLSearchParams({ model: 'newton', status: 'RUNNING', limit: '20' });

  const response = await fetch(
    `https://api.u1.archetypeai.app/v0.6/fine_tuning/jobs?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
      }
    }
  );

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

<ResponseExample>
  ```json 200 - A page of fine-tuning jobs theme={"system"}
  {
    "object": "list",
    "data": [
      {
        "object": "fine_tuning.job",
        "id": "your-job-id",
        "name": "my-tune",
        "model": "newton",
        "created_at": 1765201323,
        "org_id": "your-org",
        "status": "RUNNING",
        "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": []
      }
    ],
    "has_more": false
  }
  ```
</ResponseExample>