Skip to content
Hayonix

API reference · Fine-tuning

List fine-tuning jobs, newest first

GET/v1/fine-tunes
API keyfine_tune_job:readProjectPaginated
TypeScript
client.fineTuning.list()
Python
client.fine_tuning.list()
CLI
hayonix fine-tunes list

The project's jobs with their progress, billing and, for succeeded jobs, the resulting model. Filter with state.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the fine_tune_job:read permission (a key's scope, or a role that includes it).

Examples

The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.

curl -sS "$API_BASE_URL/fine-tunes" \
  -H "Authorization: Bearer $API_KEY"

Request

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

  • statestring

    Only jobs in this state

    One ofqueuedlaunchingtrainingsucceededfailedcancelledstopped

Response

200 a page of results — A page of jobs

  • dataarray of FineTunerequired

    The items of this page.

    Show 25 fields of data
    • idstringrequired

      Unique ID (`ftj_…`)

      ID with prefix ftj_

    • objectstringrequired

      Always `fine_tune`: the type of this object

      One offine_tune

    • project_idstringrequired

      Project it belongs to

      ID with prefix prj_

    • statestringrequired

      queued (credit reserved, waiting for compute) → launching (the training environment is starting) → training → succeeded | failed | cancelled | stopped (stopped by billing: out of credit, spend limit or suspension)

      One ofqueuedlaunchingtrainingsucceededfailedcancelledstopped

    • stagestring | nullrequired

      Finer detail of what the job is doing while launching or training, such as `waiting_for_compute` or `training`; null otherwise

    • modelstringrequired

      Base model slug

    • base_model_idstringrequired

      ID of the base model

      ID with prefix mdl_

    • methodstringrequired

      The training method (see `config.method`)

      One ofsupervisedpreference

    • adapter_typestringrequired

      `lora`: trains a low-rank adapter; `full`: updates every weight

      One oflorafull

    • training_file_idstringrequired

      ID of the training file

      ID with prefix file_

    • validation_file_idstring | nullrequired

      ID of the validation file

      ID with prefix file_

    • continue_from_checkpoint_idstring | nullrequired

      ID of the continue from checkpoint

      ID with prefix ftc_

    • suffixstring | nullrequired

      Part of the result model's name, as given at creation; null when none was given

    • configobjectrequired

      Method, adapter, hyperparameters, evaluation, early stopping and checkpoint settings, defaults filled in

    • integrationsobjectrequired

      Export hooks (secret IDs only, never values)

    • hardwareobjectrequired

      Where the job trains: SKU, GPUs (0 on a CPU SKU) and region

      Show 3 fields of hardware
      • skustringrequired

        Hardware type code

      • gpu_countintegerrequired

        Number of GPUs

      • regionstringrequired

        Region code

    • progressobjectrequired

      How far training has got

      Show 6 fields of progress
      • steps_completedintegerrequired

        Optimizer steps done

      • total_stepsinteger | nullrequired

        Optimizer steps the run will take; null until training starts

      • epochs_completednumberrequired

        Passes over the training file, fractional while one is under way

      • trained_tokensintegerrequired

        Billable training tokens processed so far

      • evaluation_tokensintegerrequired

        Billable evaluation tokens processed so far

      • early_stoppedbooleanrequired

        Training stopped early because evaluation loss stopped improving

    • billingobjectrequired

      What the job costs: billed per training and evaluation token, from credit reserved at creation

      Show 6 fields of billing
      • estimated_tokensintegerrequired

        The estimate at creation (from the files: characters / 4 plus overhead)

      • planned_tokensinteger | nullrequired

        Exact billable tokens counted just before training starts; the reserved credit is resized to their cost. Null until then.

      • reservedstringrequired

        Integer nano-USD as a decimal string

        pattern ^-?[0-9]+$

      • chargedstring | nullrequired

        Set when the job ends: tokens processed × price, never above the reservation

        pattern ^-?[0-9]+$

      • priceTrainingPrice | any JSON | nullrequired

        The training price the job is billed at (the price book in force when it was created)

        Show 5 fields of price
        • unit_pricestringrequired

          Integer nano-USD as a decimal string

          pattern ^-?[0-9]+$

        • unit_quantitystringrequired

          Tokens the unit price is for

        • per_million_tokensstringrequired

          Integer nano-USD as a decimal string

          pattern ^-?[0-9]+$

        • display_unitstring | nullrequired

          Label of the unit for display; null when none is set

        • price_book_versionintegerrequired

          Version of the price book the price comes from

      • accruedstringrequired

        Cost of the tokens processed so far at that price, never above the reservation; equals `charged` once the job has ended

        pattern ^-?[0-9]+$

    • errorobject | nullrequired

      Why the job failed, was cancelled or was stopped (for example `cancelled`, `insufficient_credit`); null otherwise

      Show 2 fields of error
      • codestringrequired

        Machine-readable code

      • messagestringrequired

        One sentence for people

    • resultobject | nullrequired

      The fine-tuned model of a succeeded job

      Show 1 field of result
      • fine_tuned_modelFineTunedModelrequired
        Show 14 fields of fine_tuned_model
        • idstringrequired

          Unique ID (`ftm_…`)

          ID with prefix ftm_

        • objectstringrequired

          Always `fine_tuned_model`: the type of this object

          One offine_tuned_model

        • project_idstringrequired

          Project it belongs to

          ID with prefix prj_

        • namestringrequired

          The model name, unique in the org

        • fine_tune_idstringrequired

          ID of the fine-tuning job

          ID with prefix ftj_

        • checkpoint_idstringrequired

          ID of the checkpoint

          ID with prefix ftc_

        • base_modelobjectrequired

          The model that was fine-tuned

          Show 2 fields of base_model
          • idstringrequired

            Unique ID (`mdl_…`)

            ID with prefix mdl_

          • slugstringrequired

            The base model's name (`publisher/name`)

        • methodstringrequired

          The training method of the job that produced it

          One ofsupervisedpreference

        • adapter_typestringrequired

          `lora`: a low-rank adapter on the base model; `full`: full weights

          One oflorafull

        • adapterobject | nullrequired

          The LoRA adapter; null for a full fine-tune

          Show 6 fields of adapter
          • formatstringrequired

            File format of the adapter

          • bytesintegerrequired

            Size in bytes

          • filesarray of objectrequired

            The files that make up the adapter

          • rankinteger | nullrequired

            LoRA rank; null when not recorded

          • alphainteger | nullrequired

            LoRA alpha; null when not recorded

          • target_modulesstring | array of string | any JSON | nullrequired

            Layers the adapter was trained on (`all-linear` or module names); null: the model's usual LoRA targets

        • merged_weightsobject | nullrequired

          Full weights: the base model with the adapter merged in, or the result of a full fine-tune; null when a LoRA job was created with `merge_weights: false`

          Show 3 fields of merged_weights
          • formatstringrequired

            File format of the weights

          • bytesintegerrequired

            Size in bytes

          • filesarray of objectrequired

            The files that make up the weights

        • catalog_model_idstring | nullrequired

          ID of the catalog model

          ID with prefix mdl_

        • servingobjectrequired

          How the model can be served: per token on the shared pool of its base model (`shared`), or on a dedicated endpoint (create one with `model.source = fine_tuned_model`)

          Show 4 fields of serving
          • availablebooleanrequired

            Callable per token right now under `name` (shared serving is ready)

          • sharedobjectrequired

            Shared (per-token) serving

          • dedicatedobjectrequired

            Whether a dedicated endpoint deployment on each engine finds weights for this model (false: creating one answers `artifact_unavailable`; llama.cpp needs the merged GGUF, which older models lack)

          • formatsarray of stringrequired

            Serving formats the model has besides its safetensors: adapter_gguf, merged_gguf (llama.cpp engines)

        • created_atstring (date-time)required

          When it was created (ISO 8601, UTC)

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

    • launched_atstring (date-time) | nullrequired

      Time launched (ISO 8601, UTC)

    • started_atstring (date-time) | nullrequired

      When it started (null until then) (ISO 8601, UTC)

    • finished_atstring (date-time) | nullrequired

      When it finished (null until then) (ISO 8601, UTC)

    • updated_atstring (date-time)required

      When it last changed (ISO 8601, UTC)

  • next_cursorstring | nullrequired

    Pass as `cursor` for the next page; null on the last page.

Example response
Example response
{
  "data": [
    {
      "id": "ftj_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "object": "fine_tune",
      "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "state": "queued",
      "stage": "string",
      "model": "string",
      "base_model_id": "mdl_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "method": "supervised",
      "adapter_type": "lora",
      "training_file_id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "validation_file_id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "continue_from_checkpoint_id": "ftc_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "suffix": "string",
      "config": {},
      "integrations": {},
      "hardware": {
        "sku": "string",
        "gpu_count": 1,
        "region": "string"
      },
      "progress": {
        "steps_completed": 1,
        "total_steps": 1,
        "epochs_completed": 1.5,
        "trained_tokens": 1,
        "evaluation_tokens": 1,
        "early_stopped": true
      },
      "billing": {
        "estimated_tokens": 1,
        "planned_tokens": 1,
        "reserved": "1500000000",
        "charged": "1500000000",
        "price": {
          "unit_price": "1500000000",
          "unit_quantity": "string",
          "per_million_tokens": "1500000000",
          "display_unit": "string",
          "price_book_version": 1
        },
        "accrued": "1500000000"
      },
      "error": {
        "code": "string",
        "message": "string"
      },
      "result": {
        "fine_tuned_model": {
          "id": "ftm_01jc5zq4m8k3v6x9t2w7r0b1e4",
          "object": "fine_tuned_model",
          "project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
          "name": "string",
          "fine_tune_id": "ftj_01jc5zq4m8k3v6x9t2w7r0b1e4",
          "checkpoint_id": "ftc_01jc5zq4m8k3v6x9t2w7r0b1e4",
          "base_model": {
            "id": "mdl_01jc5zq4m8k3v6x9t2w7r0b1e4",
            "slug": "string"
          },
          "method": "supervised",
          "adapter_type": "lora",
          "adapter": {
            "format": "string",
            "bytes": 1,
            "files": [
              null
            ],
            "rank": 1,
            "alpha": 1,
            "target_modules": null
          },
          "merged_weights": {
            "format": "string",
            "bytes": 1,
            "files": [
              null
            ]
          },
          "catalog_model_id": "mdl_01jc5zq4m8k3v6x9t2w7r0b1e4",
          "serving": {
            "available": true,
            "shared": {
              "state": null,
              "status": null,
              "reason": null,
              "changed_at": null,
              "price": null,
              "blocked": null
            },
            "dedicated": {
              "llama_cpp": null,
              "vllm": null
            },
            "formats": [
              null
            ]
          },
          "created_at": "2026-01-01T00:00:00.000Z"
        }
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "launched_at": "2026-01-01T00:00:00.000Z",
      "started_at": "2026-01-01T00:00:00.000Z",
      "finished_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.