ADadaptionlabs
autoscientist

Create an AutoScientist run

Changed on

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, or ingest it raw with POST /datasets when it already holds prompt and completion columns.

post/api/v1/autoscientist

Request

Request body

dataset_idstring required

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

modelstring

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.

augmentation_domain_rowsnumber

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_rowsnumber

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_keystring

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.

voucherstring

Optional discount voucher code.

max_iterationsnumber

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_ratenumber

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.

Example request

{
  "hyperparams": {
    "n_epochs": 1,
    "learning_rate": 0.00005,
    "lora_r": 8,
    "lora_trainable_modules": "q_proj,v_proj",
    "min_lr_ratio": 0.1,
    "scheduler_num_cycles": 0.5,
    "warmup_ratio": 0.03,
    "max_grad_norm": 2,
    "dpo_beta": 0.1
  }
}

Response

idstring required

AutoScientist run id.

dataset_idstring nullable required

Public id of the dataset the run trained on.

modelstring nullable required

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

status'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled' required
created_atstring date-time required
completed_atstring date-time nullable required

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

iterations_completednumber required

Number of completed iterations.

max_iterationsnumber required

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

target_win_ratenumber required

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

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

download_availableboolean required

True when the best trained artifact can be downloaded.

errorstring nullable

Why the run failed. Null unless status is failed.

Example response

{
  "best_hyperparams": {
    "n_epochs": 1,
    "learning_rate": 0.00005,
    "lora_r": 8,
    "lora_trainable_modules": "q_proj,v_proj",
    "min_lr_ratio": 0.1,
    "scheduler_num_cycles": 0.5,
    "warmup_ratio": 0.03,
    "max_grad_norm": 2,
    "dpo_beta": 0.1
  }
}

Changes

  • 7398ff1eeebaRevision changes
    • breaking

      removed the enum value constant of the request property /////

    • warning

      the ///// request property's exclusiveMinimum was set to true

    • info

      removed the constant enum value from the ///// response property for the response status

  • f4d1edd8f3d1Revision changes
    • breaking

      the request property's min was increased to 0.50

    • breaking

      the response's property type changed from object to number for status

    • breaking

      the response's property type changed from object to string, and format from no format to date-time for status

    • breaking

      the response's property type changed from object to string for status

    • breaking

      the response's property type changed from object to string for status

    • breaking

      the response's property type changed from object to string for status

    • info

      the request property default value 0 was added

    • info

      the request property default value 0.5 was added

    • info

      the request property default value 0 was added

    • info

      the request property's exclusiveMinimum was decreased from true to false

    • info

      the response's property default value 0 was added for the status

    • info

      the response's property default value 0.5 was added for the status

    • info

      the response's property default value 0 was added for the status