---
title: "Recommend hyperparameters"
method: POST
path: "/api/v1/autoscientist/recommend-hyperparams"
tags: ["autoscientist"]
---

# Recommend hyperparameters

`POST /api/v1/autoscientist/recommend-hyperparams`

## Request

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

Returns the hyperparameters AutoScientist derives for a model and the dataset's effective training size (rows plus planned augmentation). Nothing is launched. Omit `model` to size against the model POST /autoscientist would select for this dataset; the resolved id is returned with the values. POST /autoscientist applies the same values when `hyperparams` is omitted.

## Request body

- PublicRecommendHyperparamsDto
  - `dataset_id` string, required: The dataset the hyperparameters are sized for. Must be a dataset you own that has finished processing.
  - `model` string: Base model id from GET /autoscientist/models to tune for. Omit to size the recommendation against the model POST /autoscientist selects for this dataset; the resolved id is returned in the response `model` field. That pick assumes no `column_mapping`, so a create request supplying `column_mapping.reasoning_trace` can resolve a different model. Pass the returned `model` back on create to pin it.
  - `augmentation_domain_rows` number: Number of synthetic domain-targeted rows you plan to generate. These are additional to your own rows and count toward the effective training size, so the recommendation matches what you will launch. Defaults to 0 (no augmentation).
  - `augmentation_general_rows` number: Number of synthetic general-diversity rows you plan to generate. These are additional to your own rows and count toward the effective training size. Defaults to 0 (no augmentation).

## Response `200`

- PublicRecommendHyperparamsResponseDto
  - `model` string, required: Resolved base model id the recommendation is sized for: the value you sent, or the automatically selected model when `model` was omitted. Pass it back as `model` on POST /autoscientist to launch against the same model.
  - `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.

## Other responses

- `404`: Dataset not found or not owned by caller.
- `422`: Dataset is not ready, or the model id is unsupported.
- `503`: AutoScientist is currently unavailable.

## Changes

- **2026-10-20** `7398ff1eeeba`: 1 info
  - removed the `constant` enum value from the `hyperparams/allOf[#/components/schemas/PublicAutoScientistHyperparamsDto]/lr_scheduler_type` response property for the response status `200`
- **2026-09-15** `f4d1edd8f3d1`: 3 info
  - the `lora_dropout` response's property default value `0` was added for the status `200`
  - the `scheduler_num_cycles` response's property default value `0.5` was added for the status `200`
  - the `weight_decay` response's property default value `0` was added for the status `200`

[Operation history](https://skmtc.dev/adaptionlabs/apis/adaption-api/changes/api/v1/autoscientist/recommend-hyperparams/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)