## Create an AutoScientist run

**post** `/api/v1/autoscientist`

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.

### Body Parameters

- `dataset_id: string`

  The dataset to train on. Must be a dataset you own that has finished processing.

- `augmentation_domain_rows: optional number`

  Number of domain-targeted augmentation rows to add to the dataset before training. Defaults to 0.

- `augmentation_general_rows: optional number`

  Number of general-diversity augmentation rows to add to the dataset before training. Defaults to 0.

- `column_mapping: optional object { completion, prompt, reasoning_trace }`

  Which dataset columns feed training. When omitted, AutoScientist infers the mapping from the dataset. Required columns depend on the data format.

  - `completion: optional string`

    Source column holding the target completion/response. Used for supervised (sft) training.

  - `prompt: optional string`

    Source column holding the prompt/instruction text.

  - `reasoning_trace: optional string`

    Optional source column holding a reasoning trace to train on.

- `data_format: optional "chat" or "instruction"`

  How training rows are interpreted. Defaults to `chat` when omitted.

  - `"chat"`

  - `"instruction"`

- `hyperparams: optional object { base_model_size, batch_size, learning_rate, 14 more }`

  Hyperparameter overrides. By default, AutoScientist optimizes these values for the resolved model and effective dataset size. Avoid setting them unless strictly necessary.

  - `base_model_size: optional string`

  - `batch_size: optional "max" or number`

    Either Together's literal 'max' or a positive integer.

    - `"max"`

      - `"max"`

    - `number`

  - `learning_rate: optional number`

  - `lora_alpha: optional number`

    Must be 1× or 2× lora_r. Cross-field check is skipped when lora_r is not supplied alongside (the merged-config path uses generateConfig defaults).

  - `lora_dropout: optional number`

  - `lora_r: optional number`

  - `lora_trainable_modules: optional string`

    'all-linear' or comma-separated module list (e.g. 'q_proj,v_proj').

  - `lr_scheduler_type: optional "linear" or "cosine" or "constant"`

    - `"linear"`

    - `"cosine"`

    - `"constant"`

  - `max_grad_norm: optional number`

  - `min_lr_ratio: optional number`

  - `n_epochs: optional number`

  - `n_evals: optional number`

  - `scheduler_num_cycles: optional number`

    HyperparamService.generateConfig defaults to 0.5 (half-cycle cosine decay). Range floor is relaxed to 0 to keep that default valid.

  - `train_on_inputs: optional boolean`

  - `training_type: optional "lora" or "full"`

    Training strategy override. AutoScientist optimizes this by default; set it only when strictly necessary.

    - `"lora"`

    - `"full"`

  - `warmup_ratio: optional number`

  - `weight_decay: optional number`

- `idempotency_key: optional string`

  Idempotency key — repeat a create with the same key to safely retry without starting a duplicate run.

- `max_iterations: optional 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.

- `model: optional string`

  Base model id from GET /training-models. By default, AutoScientist selects a suitable model. The resolved model is returned in the response `model` field.

- `target_win_rate: optional number`

  Target win rate for the AutoScientist loop (between 0 exclusive 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.

- `voucher: optional string`

  Optional discount voucher code.

### Returns

- `AutoscientistRun = object { id, completed_at, created_at, 9 more }`

  - `id: string`

    AutoScientist run id.

  - `completed_at: unknown`

  - `created_at: string`

  - `dataset_id: unknown`

    Public id of the dataset the run trained on.

  - `download_available: boolean`

    True when the best trained artifact can be downloaded.

  - `iterations_completed: number`

    Number of completed iterations.

  - `max_iterations: number`

    Resolved maximum number of iterations, including the model-specific default.

  - `model: unknown`

    Resolved base model id used, including an automatically selected model.

  - `status: "pending" or "running" or "succeeded" or 2 more`

    - `"pending"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

    - `"cancelled"`

  - `target_win_rate: number`

    Resolved target win rate for the AutoScientist loop, including the model-specific default.

  - `best_win_rate: optional unknown`

    Best win rate achieved so far.

  - `error: optional unknown`

    Reserved; not populated for autoscientist runs in this version.

### Example

```http
curl https://api.prod.adaptionlabs.ai/api/v1/autoscientist \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ADAPTION_API_KEY" \
    -d '{
          "dataset_id": "dataset_id"
        }'
```

#### Response

```json
{
  "id": "id",
  "completed_at": {},
  "created_at": "2019-12-27T18:11:19.117Z",
  "dataset_id": {},
  "download_available": true,
  "iterations_completed": 0,
  "max_iterations": 0,
  "model": {},
  "status": "pending",
  "target_win_rate": 0,
  "best_win_rate": {},
  "error": {}
}
```