---
title: "Create job"
method: POST
path: "/fine-tunes"
tags: ["Fine-tuning"]
---

# Create job

`POST /fine-tunes`

Create a fine-tuning job with the provided model and training data.

## Request body

- object
  - `training_file` string, required — File-ID of a training file uploaded to the Together API
  - `validation_file` string — File-ID of a validation file uploaded to the Together API
  - `packing` boolean — Whether to use sequence packing for training. This flag has no effect if the training data is in Parquet format.
  - `max_seq_length` integer — Maximum sequence length to use for training. If not specified, the maximum allowed for the model and training method will be used.
  - `model` string, required — Name of the base model to run fine-tune job on
  - `n_epochs` integer — Number of complete passes through the training dataset (higher values may improve results but increase cost and risk of overfitting)
  - `n_checkpoints` integer — Number of intermediate model versions saved during training for evaluation
  - `n_evals` integer — Number of evaluations to be run on a given validation set during training
  - `batch_size` union — Number of training examples processed together (larger batches use more memory but may train faster). Defaults to "max". We use training optimizations like packing, so the effective batch size may be different than the value you set.
    - integer
    - 'max'
  - `gradient_accumulation_steps` integer — Number of steps to accumulate gradients before performing a weight update. If omitted or set to 0, the model default is used.
  - `learning_rate` number — Controls how quickly the model adapts to new information (too high may cause instability, too low may slow convergence)
  - `lr_scheduler` LRScheduler
    - `lr_scheduler_type` 'linear' | 'cosine', required
    - `lr_scheduler_args` union
      - LinearLRSchedulerArgs
        - `min_lr_ratio` number — The ratio of the final learning rate to the peak learning rate
      - CosineLRSchedulerArgs
        - `min_lr_ratio` number, required — The ratio of the final learning rate to the peak learning rate
        - `num_cycles` number, required — Number or fraction of cycles for the cosine learning rate scheduler
  - `warmup_ratio` number — The percent of steps at the start of training to linearly increase the learning rate.
  - `max_grad_norm` number — Max gradient norm to be used for gradient clipping. Set to 0 to disable.
  - `weight_decay` number — Weight decay. Regularization parameter for the optimizer.
  - `random_seed` integer, nullable — Random seed for reproducible training. When set, the same seed produces the same run (e.g. data shuffle, init). If omitted or null, the server applies its default seed (e.g. 42).
  - `early_stopping_enabled` boolean — Whether to stop training early when validation loss stops improving. Requires a validation_file, and n_evals must be at least early_stopping_patience + early_stopping_warmup_evals + 1 so a plateau can be detected.
  - `early_stopping_patience` integer — Number of consecutive evaluations with no improvement in validation loss to allow before stopping. Only applies when early_stopping_enabled is true.
  - `early_stopping_min_delta` number — Minimum decrease in validation loss for an evaluation to count as an improvement. Larger values treat small gains as non-improvements, causing training to stop sooner. Only applies when early_stopping_enabled is true.
  - `early_stopping_warmup_evals` integer, nullable — Number of initial evaluations excluded from the early-stopping decision. These still establish the baseline validation loss but do not count toward patience. Set to 0 to disable warmup; if omitted, defaults to 1. Only applies when early_stopping_enabled is true.
  - `suffix` string — Suffix to add to your fine-tuned model name. Must be at most 64 characters long.
  - `wandb_api_key` string — Integration key for tracking experiments and model metrics on W&B platform
  - `wandb_base_url` string — The base URL of a dedicated Weights & Biases instance.
  - `wandb_project_name` string — The Weights & Biases project for your run. If not specified, uses `together` as the project name.
  - `wandb_name` string — The Weights & Biases name for your run.
  - `wandb_entity` string — The Weights & Biases entity for your run.
  - `train_on_inputs` boolean — Whether to mask user messages in conversational data or prompts in instruction data.
  - `training_method` union — The training method to use. 'sft' for Supervised Fine-Tuning or 'dpo' for Direct Preference Optimization.
    - object
      - `method` 'sft', required
      - `train_on_inputs` boolean, required — Whether to mask user messages in conversational data or prompts in instruction data.
    - object
      - `method` 'dpo', required
      - `dpo_beta` number
      - `rpo_alpha` number
      - `dpo_normalize_logratios_by_length` boolean
      - `dpo_reference_free` boolean
      - `simpo_gamma` number
  - `training_type` union — The training type to use. Defaults to LoRA if not provided.
    - object
      - `type` 'Full', required
    - object — LoRA training configuration for a fine-tuning job.
      - `type` 'Lora', required — Identifies this request as a LoRA fine-tune.
      - `lora_r` integer, required — Rank of the LoRA adapter matrices.
      - `lora_alpha` integer, required — Scaling factor applied to the LoRA adapter weights.
      - `lora_dropout` number — Dropout probability applied to LoRA adapter inputs.
      - `lora_trainable_modules` string — Comma-separated LoRA target modules. Use `all-linear` for model defaults; MoE expert modules (`w_up`, `w_gate`, `w_down`) can be combined with attention modules on compatible models. Fine-tunes that target any expert module produce adapter-only output.
  - `multimodal_params` MultimodalParams
    - `train_vision` boolean — Whether to train the vision encoder of the model. Only available for multimodal models.
  - `from_checkpoint` string — The checkpoint identifier to continue training from a previous fine-tuning job. Format is `{$JOB_ID}` or `{$OUTPUT_MODEL_NAME}` or `{$JOB_ID}:{$STEP}` or `{$OUTPUT_MODEL_NAME}:{$STEP}`. The step value is optional; without it, uses the final checkpoint.
  - `from_hf_model` string — The Hugging Face Hub repo to start training from. Should be as close as possible to the base model (specified by the `model` argument) in terms of architecture and size.
  - `hf_model_revision` string — The revision of the Hugging Face Hub model to continue training from. E.g., hf_model_revision=main (default, used if the argument is not provided) or hf_model_revision='607a30d783dfa663caf39e06633721c8d4cfcd7e' (specific commit).
  - `hf_api_token` string — The API token for the Hugging Face Hub.
  - `hf_output_repo_name` string — The name of the Hugging Face repository to upload the fine-tuned model to.

## Response `200`

Fine-tuning job initiated successfully

- FinetuneResponseTruncated — A truncated version of the fine-tune response, used for POST /fine-tunes, GET /fine-tunes and POST /fine-tunes/{id}/cancel endpoints
  - `id` string, required — Unique identifier for the fine-tune job
  - `status` 'pending' | 'queued' | 'running' | 'compressing' | 'uploading' | 'cancel_requested' | 'cancelled' | 'error' | 'completed', required
  - `created_at` string, date-time, required — Creation timestamp of the fine-tune job
  - `updated_at` string, date-time, required — Last update timestamp of the fine-tune job
  - `started_at` string, date-time — Start timestamp of the current stage of the fine-tune job
  - `user_id` string, required — ID of the user who created the fine-tune job.
  - `owner_address` string — Owner address information
  - `total_price` integer — Total price for the fine-tuning job
  - `token_count` integer — Count of tokens processed
  - `events` FineTuneEvent[] — Events related to this fine-tune job
    - `object` 'fine-tune-event', required — The object type, which is always `fine-tune-event`.
    - `created_at` string, required
    - `level` string
    - `message` string, required
    - `type` 'job_pending' | 'job_start' | 'job_stopped' | 'model_downloading' | 'model_download_complete' | 'training_data_downloading' | 'training_data_download_complete' | 'validation_data_downloading' | 'validation_data_download_complete' | 'wandb_init' | 'training_start' | 'checkpoint_save' | 'billing_limit' | 'epoch_complete' | 'training_complete' | 'model_compressing' | 'model_compression_complete' | 'model_uploading' | 'model_upload_complete' | 'job_complete' | 'job_error' | 'cancel_requested' | 'job_restarted' | 'refund' | 'warning' | 'early_stopped' | 'tokenized_dataset_upload_complete', required
    - `param_count` integer
    - `token_count` integer
    - `total_steps` integer
    - `wandb_url` string
    - `step` integer
    - `checkpoint_path` string
    - `model_path` string
    - `tokenized_dataset_path` string — Storage path for the tokenized dataset archive associated with this event.
    - `early_stopping_best_step` integer, nullable — For early_stopped events, the selected best-checkpoint step when a finite best metric exists. If early_stopping_best_metric_value is null, this is the halt step.
    - `early_stopping_best_metric_value` number, nullable — For early_stopped events, the best validation loss observed. Null if no improving evaluation was recorded.
  - `training_file` string — File-ID of the training file
  - `validation_file` string — File-ID of the validation file
  - `packing` boolean — Whether sequence packing is being used for training.
  - `max_seq_length` integer — Maximum sequence length to use for training. If not specified, uses the maximum allowed for the model and training method.
  - `model` string — Base model used for fine-tuning
  - `model_output_name` string
  - `suffix` string — Suffix added to the fine-tuned model name
  - `n_epochs` integer — Number of training epochs
  - `n_evals` integer — Number of evaluations during training
  - `n_checkpoints` integer — Number of checkpoints saved during training
  - `batch_size` integer — Batch size used for training
  - `training_type` union — Type of training used (full or LoRA)
    - FullTrainingType
      - `type` 'Full', required
    - LoRATrainingType — LoRA training configuration for a fine-tuning job.
      - `type` 'Lora', required — Identifies this request as a LoRA fine-tune.
      - `lora_r` integer, required — Rank of the LoRA adapter matrices.
      - `lora_alpha` integer, required — Scaling factor applied to the LoRA adapter weights.
      - `lora_dropout` number — Dropout probability applied to LoRA adapter inputs.
      - `lora_trainable_modules` string — Comma-separated LoRA target modules. Use `all-linear` for model defaults; MoE expert modules (`w_up`, `w_gate`, `w_down`) can be combined with attention modules on compatible models. Fine-tunes that target any expert module produce adapter-only output.
  - `training_method` union — Method of training used
    - TrainingMethodSFT
      - `method` 'sft', required
      - `train_on_inputs` boolean, required — Whether to mask user messages in conversational data or prompts in instruction data.
    - TrainingMethodDPO
      - `method` 'dpo', required
      - `dpo_beta` number
      - `rpo_alpha` number
      - `dpo_normalize_logratios_by_length` boolean
      - `dpo_reference_free` boolean
      - `simpo_gamma` number
  - `learning_rate` number — Learning rate used for training
  - `lr_scheduler` LRScheduler
    - `lr_scheduler_type` 'linear' | 'cosine', required
    - `lr_scheduler_args` union
      - LinearLRSchedulerArgs
        - `min_lr_ratio` number — The ratio of the final learning rate to the peak learning rate
      - CosineLRSchedulerArgs
        - `min_lr_ratio` number, required — The ratio of the final learning rate to the peak learning rate
        - `num_cycles` number, required — Number or fraction of cycles for the cosine learning rate scheduler
  - `warmup_ratio` number — Ratio of warmup steps
  - `max_grad_norm` number — Maximum gradient norm for clipping
  - `weight_decay` number — Weight decay value used
  - `random_seed` integer, nullable — Random seed used for training. Integer when set; null if not stored (e.g. legacy jobs) or no explicit seed was recorded.
  - `wandb_project_name` string — Weights & Biases project name
  - `wandb_name` string — Weights & Biases run name
  - `from_checkpoint` string — Checkpoint used to continue training
  - `from_hf_model` string — Hugging Face Hub repo to start training from
  - `hf_model_revision` string — The revision of the Hugging Face Hub model to continue training from
  - `progress` FineTuneProgress — Progress information for a fine-tuning job
    - `estimate_available` boolean, required — Whether time estimate is available
    - `seconds_remaining` integer, required — Estimated time remaining in seconds for the fine-tuning job to next state
  - `early_stopped` boolean — Whether the early-stopping criterion triggered.
  - `early_stopping_best_step` integer — Step associated with the selected early-stopping artifact. When early_stopping_best_metric is null, no finite best metric was recorded; this is the halt step, not a best-checkpoint step.
  - `early_stopping_best_metric` number, nullable — Best validation loss observed, corresponding to early_stopping_best_step. Null if no improving evaluation was recorded.

---

[API](https://skmtc.net/together/apis/together-apis.md) · [All operations](https://skmtc.net/together/apis/together-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/together/together-apis/revisions/1fab430e87d6/schema)