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. The dataset must have finished processing: adapt it first with POST /datasets/{dataset_id}/run, or ingest it raw with POST /datasets when it already holds prompt and completion columns.

Body ParametersJSONExpand Collapse

dataset_id: string

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

model: optional 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: optional "instruction" or "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.

One of the following:

"instruction"

"alignment"

data_format: optional "chat" or "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.

One of the following:

"chat"

"instruction"

column_mapping: optional object { prompt, completion, reasoning_trace, 2 more }

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

prompt: optional string

Source column holding the prompt/instruction text.

completion: optional string

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

reasoning_trace: optional string

Optional source column holding a reasoning trace to train on.

chosen: optional 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: optional string

Source column holding the rejected response. Pair it with chosen.

hyperparams: optional object { training_type, n_epochs, learning_rate, 16 more }

Hyperparameter overrides. Not advised. AutoScientist derives these values from the resolved model and the effective dataset size; any field supplied here replaces the derived value for that field. Most fields therefore have no fixed default — where one is listed below it is a constant, and everything else is computed per run. Call POST /autoscientist/recommend-hyperparams to inspect the derived values for a dataset without launching a run.

training_type: optional "lora" or "full"

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

One of the following:

"lora"

"full"

n_epochs: optional number

minimum1

maximum20

learning_rate: optional number

minimum1e-8

maximum0.01

batch_size: optional "max" or number

Either the literal ‘max’ or an integer of 1 or more. No fixed upper bound: the ceiling depends on the model and hardware, and a larger value is rejected at launch. Defaults to ‘max’.

One of the following:

"max"

number

lora_r: optional number

minimum1

maximum64

lora_alpha: optional 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: optional number

Dropout applied to the LoRA layers. Defaults to 0.

minimum0

maximum1

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"

One of the following:

"linear"

"cosine"

"constant"

min_lr_ratio: optional number

minimum0

maximum1

scheduler_num_cycles: optional number

Number of cosine decay cycles across training. Defaults to 0.5, a single half-cycle decay from the peak learning rate down to the floor.

minimum0

maximum4

warmup_ratio: optional number

minimum0

maximum1

max_grad_norm: optional number

minimum0

weight_decay: optional number

L2 penalty applied to the weights. Defaults to 0.

minimum0

train_on_inputs: optional 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: optional 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.

minimum0.05

maximum0.9

dpo_normalize_logratios_by_length: optional boolean

Normalizes log ratios by sample length during DPO loss calculation. Automatically set to true when simpo_gamma > 0.

rpo_alpha: optional number

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.

formatfloat

minimum0

simpo_gamma: optional number

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.

formatfloat

minimum0

augmentation_domain_rows: optional 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).

minimum0

maximum40000

augmentation_general_rows: optional 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).

minimum0

maximum50000

idempotency_key: optional 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: optional string

Optional discount voucher code.

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.

minimum1

maximum5

target_win_rate: optional 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.

minimum0.5

maximum1

exclusiveMinimum

exclusiveMaximum

ReturnsExpand Collapse

AutoscientistRun object { id, dataset_id, model, 12 more }

id: string

AutoScientist run id.

dataset_id: string

Public id of the dataset the run trained on.

model: string

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

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

One of the following:

"pending"

"running"

"succeeded"

"failed"

"cancelled"

created_at: string

formatdate-time

completed_at: string

When the run reached a terminal state. Null while it is still running.

formatdate-time

iterations_completed: number

Number of completed iterations.

max_iterations: number

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

target_win_rate: number

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

best_win_rate: optional number

Best win rate achieved so far.

training_method: "instruction" or "alignment"

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.

One of the following:

"instruction"

"alignment"

best_hyperparams: object { training_type, n_epochs, learning_rate, 16 more }

Hyperparameters that produced the best iteration so far, and the ones the downloadable artifact was trained with. Null until an iteration completes.

training_type: optional "lora" or "full"

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

One of the following:

"lora"

"full"

n_epochs: optional number

minimum1

maximum20

learning_rate: optional number

minimum1e-8

maximum0.01

batch_size: optional "max" or number

Either the literal ‘max’ or an integer of 1 or more. No fixed upper bound: the ceiling depends on the model and hardware, and a larger value is rejected at launch. Defaults to ‘max’.

One of the following:

"max"

number

lora_r: optional number

minimum1

maximum64

lora_alpha: optional 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: optional number

Dropout applied to the LoRA layers. Defaults to 0.

minimum0

maximum1

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"

One of the following:

"linear"

"cosine"

"constant"

min_lr_ratio: optional number

minimum0

maximum1

scheduler_num_cycles: optional number

Number of cosine decay cycles across training. Defaults to 0.5, a single half-cycle decay from the peak learning rate down to the floor.

minimum0

maximum4

warmup_ratio: optional number

minimum0

maximum1

max_grad_norm: optional number

minimum0

weight_decay: optional number

L2 penalty applied to the weights. Defaults to 0.

minimum0

train_on_inputs: optional boolean

dpo_beta: optional 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.

minimum0.05

maximum0.9

dpo_normalize_logratios_by_length: optional boolean

Normalizes log ratios by sample length during DPO loss calculation. Automatically set to true when simpo_gamma > 0.

rpo_alpha: optional number

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.

formatfloat

minimum0

simpo_gamma: optional number

formatfloat

minimum0

column_mapping: object { prompt, completion, reasoning_trace, 2 more }

Column mapping the run trained with, echoing what was sent on create. Null when the mapping was left to the platform to infer.

prompt: optional string

Source column holding the prompt/instruction text.

completion: optional string

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

reasoning_trace: optional string

Optional source column holding a reasoning trace to train on.

chosen: optional 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: optional string

Source column holding the rejected response. Pair it with chosen.

download_available: boolean

True when the best trained artifact can be downloaded.

error: optional string

Why the run failed. Null unless status is failed.

Create an AutoScientist run

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"
        }'

{
  "id": "id",
  "dataset_id": "dataset_id",
  "model": "model",
  "status": "pending",
  "created_at": "2019-12-27T18:11:19.117Z",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "iterations_completed": 0,
  "max_iterations": 0,
  "target_win_rate": 0,
  "best_win_rate": 0,
  "training_method": "instruction",
  "best_hyperparams": {
    "training_type": "lora",
    "n_epochs": 1,
    "learning_rate": 0.00005,
    "batch_size": "max",
    "lora_r": 8,
    "lora_alpha": 0,
    "lora_dropout": 0,
    "lora_trainable_modules": "q_proj,v_proj",
    "lr_scheduler_type": "linear",
    "min_lr_ratio": 0.1,
    "scheduler_num_cycles": 0.5,
    "warmup_ratio": 0.03,
    "max_grad_norm": 2,
    "weight_decay": 0,
    "train_on_inputs": false,
    "dpo_beta": 0.1,
    "dpo_normalize_logratios_by_length": true,
    "rpo_alpha": 0,
    "simpo_gamma": 0
  },
  "column_mapping": {
    "prompt": "prompt",
    "completion": "completion",
    "reasoning_trace": "reasoning_trace",
    "chosen": "chosen",
    "rejected": "rejected"
  },
  "download_available": true,
  "error": "error"
}

Returns Examples

{
  "id": "id",
  "dataset_id": "dataset_id",
  "model": "model",
  "status": "pending",
  "created_at": "2019-12-27T18:11:19.117Z",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "iterations_completed": 0,
  "max_iterations": 0,
  "target_win_rate": 0,
  "best_win_rate": 0,
  "training_method": "instruction",
  "best_hyperparams": {
    "training_type": "lora",
    "n_epochs": 1,
    "learning_rate": 0.00005,
    "batch_size": "max",
    "lora_r": 8,
    "lora_alpha": 0,
    "lora_dropout": 0,
    "lora_trainable_modules": "q_proj,v_proj",
    "lr_scheduler_type": "linear",
    "min_lr_ratio": 0.1,
    "scheduler_num_cycles": 0.5,
    "warmup_ratio": 0.03,
    "max_grad_norm": 2,
    "weight_decay": 0,
    "train_on_inputs": false,
    "dpo_beta": 0.1,
    "dpo_normalize_logratios_by_length": true,
    "rpo_alpha": 0,
    "simpo_gamma": 0
  },
  "column_mapping": {
    "prompt": "prompt",
    "completion": "completion",
    "reasoning_trace": "reasoning_trace",
    "chosen": "chosen",
    "rejected": "rejected"
  },
  "download_available": true,
  "error": "error"
}