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 ParametersJSONExpand Collapse

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.

One of the following:

"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.

One of the following:

"max"

number

learning_rate: optional number

minimum1e-8

maximum0.01

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

minimum0

maximum1

lora_r: optional number

minimum1

maximum64

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"

max_grad_norm: optional number

minimum0

min_lr_ratio: optional number

minimum0

maximum1

n_epochs: optional number

minimum1

maximum20

n_evals: optional number

minimum1

maximum100

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.

minimum0

maximum4

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.

One of the following:

"lora"

"full"

warmup_ratio: optional number

minimum0

maximum1

weight_decay: optional number

minimum0

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.

minimum1

maximum10

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.

minimum0

maximum1

exclusiveMinimum

exclusiveMaximum

voucher: optional string

Optional discount voucher code.

ReturnsExpand Collapse

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

id: string

AutoScientist run id.

completed_at: unknown

created_at: string

formatdate-time

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

One of the following:

"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.

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",
  "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": {}
}

Returns Examples

{
  "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": {}
}