---
title: "Create an AutoScientist run"
method: POST
path: "/api/v1/autoscientist"
tags: ["autoscientist"]
---

# Create an AutoScientist run

`POST /api/v1/autoscientist`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/adaptionlabs/apis/adaption-api/docs/api/v1/autoscientist/post.ts> (a function with typed inputs; its response is checked against the schema)

Starts an iterative AutoScientist loop on a dataset you own. The loop runs up to max_iterations training cycles, stopping early when target_win_rate is achieved. Omitted parameters are resolved to platform defaults for the selected model and returned in the response. Poll GET /autoscientist/{experiment_id} for status, then GET /autoscientist/{experiment_id}/download once it succeeds. The dataset must have finished processing: adapt it first with [POST /datasets/{dataset_id}/adapt](/api/python/resources/datasets/methods/adapt), or ingest it raw with [POST /datasets](/api/python/resources/datasets/methods/create) when it already holds prompt and completion columns.

## Request body

- PublicCreateAutoScientistRunDto
  - `dataset_id` string, required: The dataset to train on. Must be a dataset you own that has finished processing.
  - `model` string: Base model id from GET /autoscientist/models. By default, AutoScientist selects a suitable model. The resolved model is returned in the response `model` field.
  - `training_method` 'instruction' | 'alignment': Training objective. Pass `alignment` to train on preference pairs; the dataset must have been prepared with `training_type: preference_pairs`. An alignment run trains in two stages — supervised first, then preference — and this run reports the first until the second begins. Supplying `alignment` for any other dataset has no effect: there are no rejected responses to train against, so the run stays `instruction`. Omitted, it defaults to `instruction` unless an alignment run was already configured for this dataset in the dashboard.
  - `data_format` 'chat' | 'instruction': Encoding used for the training rows handed to the training provider. Applies to raw datasets only — for an adapted dataset the platform resolves the encoding and this value is ignored. Defaults to `chat`.
  - `column_mapping` PublicTrainingColumnMappingDto
    - `prompt` string: Source column holding the prompt/instruction text.
    - `completion` string: Source column holding the target completion/response. Used for supervised (sft) training.
    - `reasoning_trace` string: Optional source column holding a reasoning trace to train on. Supported on instruction runs with a model whose GET /autoscientist/models entry reports `train_with_reasoning: true`; naming it with any other model on such a run is rejected.
    - `chosen` string: Source column holding the preferred response. Used for preference (dpo) training, where a row carries two completions rather than one. Pair it with `rejected`.
    - `rejected` string: Source column holding the rejected response. Pair it with `chosen`.
  - `hyperparams` PublicAutoScientistHyperparamsDto
    - `training_type` 'lora' | 'full': Training strategy override. AutoScientist optimizes this by default; set it only when strictly necessary.
    - `n_epochs` number
    - `learning_rate` number
    - `batch_size` union: Either the literal 'max' or an integer of 1 or more. The allowed range depends on the base model, the training type (LoRA or full) and the training method (DPO is often lower than SFT); a launch with a value outside it is rejected with a 400 that names the range. 'max' always fits. Defaults to 'max'.
      - 'max'
      - integer
    - `lora_r` number
    - `lora_alpha` number: Must be 1× or 2× lora_r. Only checked when you supply lora_r in the same request; otherwise it is validated against the platform default.
    - `lora_dropout` number: Dropout applied to the LoRA layers. Defaults to 0.
    - `lora_trainable_modules` string: 'all-linear' or comma-separated module list (e.g. 'q_proj,v_proj').
    - `lr_scheduler_type` 'linear' | 'cosine'
    - `min_lr_ratio` number
    - `scheduler_num_cycles` number: Number of cosine decay cycles across training. Must be greater than 0. Defaults to 0.5, a single half-cycle decay from the peak learning rate down to the floor.
    - `warmup_ratio` number
    - `max_grad_norm` number
    - `weight_decay` number: L2 penalty applied to the weights. Defaults to 0.
    - `train_on_inputs` boolean: Whether training loss is computed over the prompt tokens as well as the completion. `true` trains on the full sequence, `false` trains only on the completion. Omit to let the platform decide per example, which is the default.
    - `dpo_beta` number: Controls how much the model can deviate from the reference model. Lower = more aggressive updates toward preferred responses; higher = stays closer to reference behavior.
    - `dpo_normalize_logratios_by_length` boolean: Normalizes log ratios by sample length during DPO loss calculation. Automatically set to true when simpo_gamma > 0.
    - `rpo_alpha` number, float: RPO loss modifier: incorporates the NLL loss on selected samples with this weight. Defaults to 0.0 (standard DPO loss). Mutually exclusive with simpo_gamma — both above 0 is rejected.
    - `simpo_gamma` number, float: SimPO loss modifier: adds a margin to the loss, force-enables length normalization, and excludes reference logits. Defaults to 0.0 (off). Raise dpo_beta alongside it. Mutually exclusive with rpo_alpha — both above 0 is rejected.
  - `augmentation_domain_rows` number: Number of synthetic domain-targeted rows to generate and append to the dataset before training. These are additional to your own rows, not a resampling of them, and count toward the effective training size used to derive hyperparameters. Defaults to 0 (no augmentation).
  - `augmentation_general_rows` number: Number of synthetic general-diversity rows to generate and append to the dataset before training. These are additional to your own rows, not a resampling of them, and count toward the effective training size used to derive hyperparameters. Defaults to 0 (no augmentation).
  - `idempotency_key` string: Client-generated key for safe retries. Scoped to `dataset_id`: while a run started with this key is still in progress, repeating the request returns that run instead of starting a second one. Once the run reaches a terminal state (succeeded, failed or cancelled) the key no longer matches and the same request starts a new run.
  - `voucher` string: Optional discount voucher code.
  - `max_iterations` number: Maximum number of iterations to run. Defaults to the resolved model configuration (currently 3). The resolved value is returned in the response `max_iterations` field.
  - `target_win_rate` number: Target win rate for the AutoScientist loop (between 0.5 and 1 inclusive). Defaults to 0.7 for small models and 0.8 for larger models. The resolved value is returned in the response `target_win_rate` field.

## Response `202`

- PublicAutoScientistRunDto
  - `id` string, required: AutoScientist run id.
  - `dataset_id` string, nullable, required: Public id of the dataset the run trained on.
  - `model` string, nullable, required: Resolved base model id used, including an automatically selected model.
  - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
  - `created_at` string, date-time, required
  - `completed_at` string, date-time, nullable, required: When the run reached a terminal state. Null while it is still running.
  - `iterations_completed` number, required: Number of completed iterations.
  - `max_iterations` number, required: Resolved maximum number of iterations, including the model-specific default.
  - `target_win_rate` number, required: Resolved target win rate for the AutoScientist loop, including the model-specific default.
  - `best_win_rate` number, nullable: Best win rate achieved so far.
  - `training_method` 'instruction' | 'alignment', required: The objective this run is training. Resolved at creation — a requested `alignment` is downgraded to `instruction` when the dataset is not preference pairs, so read this back to confirm what actually runs.
  - `best_hyperparams` PublicAutoScientistHyperparamsDto, required
    - `training_type` 'lora' | 'full': Training strategy override. AutoScientist optimizes this by default; set it only when strictly necessary.
    - `n_epochs` number
    - `learning_rate` number
    - `batch_size` union: Either the literal 'max' or an integer of 1 or more. The allowed range depends on the base model, the training type (LoRA or full) and the training method (DPO is often lower than SFT); a launch with a value outside it is rejected with a 400 that names the range. 'max' always fits. Defaults to 'max'.
      - 'max'
      - integer
    - `lora_r` number
    - `lora_alpha` number: Must be 1× or 2× lora_r. Only checked when you supply lora_r in the same request; otherwise it is validated against the platform default.
    - `lora_dropout` number: Dropout applied to the LoRA layers. Defaults to 0.
    - `lora_trainable_modules` string: 'all-linear' or comma-separated module list (e.g. 'q_proj,v_proj').
    - `lr_scheduler_type` 'linear' | 'cosine'
    - `min_lr_ratio` number
    - `scheduler_num_cycles` number: Number of cosine decay cycles across training. Must be greater than 0. Defaults to 0.5, a single half-cycle decay from the peak learning rate down to the floor.
    - `warmup_ratio` number
    - `max_grad_norm` number
    - `weight_decay` number: L2 penalty applied to the weights. Defaults to 0.
    - `train_on_inputs` boolean: Whether training loss is computed over the prompt tokens as well as the completion. `true` trains on the full sequence, `false` trains only on the completion. Omit to let the platform decide per example, which is the default.
    - `dpo_beta` number: Controls how much the model can deviate from the reference model. Lower = more aggressive updates toward preferred responses; higher = stays closer to reference behavior.
    - `dpo_normalize_logratios_by_length` boolean: Normalizes log ratios by sample length during DPO loss calculation. Automatically set to true when simpo_gamma > 0.
    - `rpo_alpha` number, float: RPO loss modifier: incorporates the NLL loss on selected samples with this weight. Defaults to 0.0 (standard DPO loss). Mutually exclusive with simpo_gamma — both above 0 is rejected.
    - `simpo_gamma` number, float: SimPO loss modifier: adds a margin to the loss, force-enables length normalization, and excludes reference logits. Defaults to 0.0 (off). Raise dpo_beta alongside it. Mutually exclusive with rpo_alpha — both above 0 is rejected.
  - `column_mapping` PublicTrainingColumnMappingDto, required
    - `prompt` string: Source column holding the prompt/instruction text.
    - `completion` string: Source column holding the target completion/response. Used for supervised (sft) training.
    - `reasoning_trace` string: Optional source column holding a reasoning trace to train on. Supported on instruction runs with a model whose GET /autoscientist/models entry reports `train_with_reasoning: true`; naming it with any other model on such a run is rejected.
    - `chosen` string: Source column holding the preferred response. Used for preference (dpo) training, where a row carries two completions rather than one. Pair it with `rejected`.
    - `rejected` string: Source column holding the rejected response. Pair it with `chosen`.
  - `download_available` boolean, required: True when the best trained artifact can be downloaded.
  - `error` string, nullable: Why the run failed. Null unless `status` is `failed`.

## Other responses

- `400`: Invalid request — dataset has too few training rows, or an unsupported configuration was supplied.
- `402`: Insufficient credits to start this run.
- `403`: Fine-tuning is not available on your current plan. Upgrade to unlock this feature.
- `404`: Dataset not found or not owned by caller.
- `422`: The dataset is not ready for training yet — its preparation is still running, failed, or was never started.
- `429`: Too many training jobs in flight. Wait for an existing run to complete before starting another.
- `503`: AutoScientist is currently unavailable.

## Changes

- **2026-10-20** `7398ff1eeeba`: 1 breaking, 1 warning, 1 info
  - removed the enum value `constant` of the request property `hyperparams/allOf[#/components/schemas/PublicAutoScientistHyperparamsDto]/lr_scheduler_type`
  - the `hyperparams/allOf[#/components/schemas/PublicAutoScientistHyperparamsDto]/scheduler_num_cycles` request property's exclusiveMinimum was set to `true`
  - removed the `constant` enum value from the `best_hyperparams/allOf[#/components/schemas/PublicAutoScientistHyperparamsDto]/lr_scheduler_type` response property for the response status `202`
- **2026-09-15** `f4d1edd8f3d1`: 6 breaking, 7 info
  - the `target_win_rate` request property's min was increased to `0.50`
  - the `best_win_rate` response's property type changed from `object` to `number` for status `202`
  - the `completed_at` response's property type changed from `object` to `string`, and format from no format to `date-time` for status `202`
  - the `dataset_id` response's property type changed from `object` to `string` for status `202`
  - …9 more

[Operation history](https://skmtc.dev/adaptionlabs/apis/adaption-api/changes/api/v1/autoscientist/post.md)

---

[API](https://skmtc.dev/adaptionlabs/apis/adaption-api.md) - [All operations](https://skmtc.dev/adaptionlabs/apis/adaption-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adaptionlabs/apis/adaption-api/revisions/d4cf908c19a0?raw)