---
title: "Adapt a dataset (or estimate cost)"
method: POST
path: "/api/v1/datasets/{dataset_id}/adapt"
tags: ["Dataset"]
---

# Adapt a dataset (or estimate cost)

`POST /api/v1/datasets/{dataset_id}/adapt`

## Request

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

Validates column mapping and recipe configuration, reserves credits, and starts the adaptation pipeline, which improves the rows already in the dataset without changing how many there are. To add rows instead, use POST /datasets/{dataset_id}/augment. Set estimate=true to validate and get a cost quote without starting a run. When the mapped image column is also in context_columns, output rows are billed at 10 credits per 100 rows (1–100 rows cost 10 credits; see multimodalPricingApplied and creditMultiplier on the response). Once the run succeeds, train on the result with [POST /autoscientist](/api/python/resources/autoscientist/methods/create).

## Path parameters

- `dataset_id` string, required

## Request body

- PublicLaunchDto
  - `column_mapping` PublicColumnMappingDto
    - `prompt` string: Column to use as the prompt/instruction field. Trigger for prompt mode (with optional `completion` and `context`); cannot be combined with `chat` or `universal_prompt`.
    - `completion` string: Column to use as the completion/response field. Optional in prompt mode and universal-prompt mode; not allowed in chat mode.
    - `chat` string: Column containing chat/conversation data. Chat mode is exclusive: `prompt`, `completion`, `context` and `universal_prompt` must be omitted. An `image` column may accompany it — chat supplies the text framing an image column needs.
    - `context` string[]: Columns to include as context. Optional in prompt mode; required (at least one entry) in universal-prompt mode; not allowed in chat mode.
    - `universal_prompt` string: Dataset-wide instruction folded into every row alongside the context columns. Use when there is no per-row prompt column but rows share a common task framing. Requires a per-row differentiator, so that the folded prompt is not identical on every row: at least one entry in `context`, or an `image` column.
    - `image` string: Column containing per-row images (URLs, file paths, or encoded bytes) to fold into the adaptation as multimodal context. Allowed in any mode (prompt, universal-prompt, or chat) as long as text framing is also present — it cannot be the only mapping. The column is automatically added to `context` if omitted. Note: opting a dataset into multimodal context disqualifies it from finetuning.
  - `recipe_specification` PublicRecipeSpecDto
    - `version` string: Reserved. Accepted and stored for forward compatibility, but not yet read — recipe options are currently versioned by release rather than by this field. Omit it.
    - `recipes` RecipeOptionsDto
      - `prompt_rephrase` boolean: Rephrase prompts for variety and clarity
      - `deduplication` boolean: Remove near-duplicate rows
      - `reasoning_traces` boolean: Add reasoning traces (chain-of-thought) to completions
  - `job_specification` PublicJobSpecDto
    - `max_rows` number: Maximum number of rows to process in this run
    - `idempotency_key` string: Client-generated idempotency key for safe retries. If a launch with the same key already exists, the original response is returned.
  - `brand_controls` PublicBrandControlsDto
    - `length` 'minimal' | 'concise' | 'detailed' | 'extensive': Target response length. Controls verbosity of generated completions.
    - `safety_categories` string[]: Turns on content-safety analysis for the generated completions. Supply one or more of `violence`, `self_harm`, `harassment`, `hate`, `sexual`. Any non-empty list enables the analysis, and every row is then scored against all five categories — the list does not narrow what is checked. Results arrive as the `prompt_safety_issues` and `response_safety_issues` columns on the adapted dataset. Rows are annotated, never removed.
    - `hallucination_mitigation` boolean: Enable web-search grounding to reduce hallucinations in generated completions.
    - `blueprint` string: Freeform brand/style instructions injected as a system prompt for every generated completion. Use this to enforce tone, language, persona, or any guideline that does not fit the structured length/safety/grounding controls.
  - `training_type` 'instruction_dataset' | 'preference_pairs': How to adapt the dataset. `instruction_dataset` (default) produces enhanced prompt/completion pairs for SFT; `preference_pairs` generates chosen/rejected pairs for DPO. Source columns are the same in both cases — `column_mapping.prompt` (and optionally `completion`) — the chosen/rejected fields are produced by the adaptation pipeline.
  - `estimate` boolean: When true, validates the request and returns the estimated credit cost without starting a run. The request’s `column_mapping` and expansion fields are still saved to the dataset, as they are what the estimate prices.
  - `translate` PublicTranslateTargetsDto
    - `languages` string[], required: Target languages, as ISO 639-1 codes. Each sampled row gains one translated row per language. Unsupported codes are rejected with a sample of the supported ones.
    - `sample_rate` number, required: Fraction of rows translated into each language. At 0.25 with two languages, 1,000 rows become 1,500.
  - `localize` PublicLocalizeTargetsDto
    - `pairs` PublicCountryLanguagePairDto[], required: Target country/language pairs. Each sampled row gains one row localized to each pair — translated into the language and adapted to that country’s conventions. Unsupported combinations are rejected.
      - `country` string, required: ISO 3166-1 alpha-2 country code.
      - `language` string, required: Language code, as ISO 639-1 — optionally with a script subtag. Supported pairs include codes that are not two letters (`zh-Hant` for Taiwan, `yue` for Hong Kong), so the length is not pinned at two here. Membership is decided against the supported-pair list, which names an unsupported entry in its own 400.
    - `sample_rate` number, required: Fraction of rows localized to each pair. At 0.25 with one pair, 1,000 rows become 1,250.
  - `expand` PublicAdaptExpandDto
    - `similar_rows` integer: New rows to generate in the style of this dataset. A sample of its rows is analysed for topic, language and prompt/completion conventions, and new rows are generated to match. Defaults to 0.
    - `domain_rows` integer: Rows to retrieve from topics matching this dataset. Defaults to 0.
    - `general_rows` integer: Rows to retrieve from other topics, to broaden the dataset. Defaults to 0.
  - `language_expansion` PublicLanguageExpansionSpecDto
    - `type` 'translate' | 'localize', required: Expansion mode. `translate` produces one new row variant per target language; `localize` produces one new row variant per country/language pair.
    - `languages` string[]: Target language codes (required when type=translate, forbidden when type=localize). Mostly ISO 639-1 two-letter codes such as `es`, with three-letter codes where no two-letter code exists (`fil`, `yue`) and script-tagged codes for Chinese (`zh-Hans`, `zh-Hant`). Matching is case-insensitive, and bare `zh` resolves to `zh-Hans`. Validated against the supported language list at request time; unknown values return 400 with a sample of supported codes.
    - `pairs` PublicCountryLanguagePairDto[]: Country/language pairs (required when type=localize, forbidden when type=translate). Each pair is validated against the supported country/language pair list at request time.
      - `country` string, required: ISO 3166-1 alpha-2 country code.
      - `language` string, required: Language code, as ISO 639-1 — optionally with a script subtag. Supported pairs include codes that are not two letters (`zh-Hant` for Taiwan, `yue` for Hong Kong), so the length is not pinned at two here. Membership is decided against the supported-pair list, which names an unsupported entry in its own 400.
    - `sample_rate` number, required: Fraction (0.01–1) of input rows that are expanded per target. Output rows ≈ input × (1 + sample_rate × target_count). Required. Credits are billed on the expanded output row count.

## Response `200`

- PublicLaunchResponseDto
  - `run_id` string, nullable: Unique identifier for this pipeline run. Null for estimate-only requests.
  - `estimatedMinutes` number, required: Estimated processing time in minutes
  - `estimatedCreditsConsumed` number, required: Estimated number of credits that will be consumed by this run
  - `estimate` boolean, required: Whether this was an estimate-only request (no run started)
  - `multimodalPricingApplied` boolean, required: True when an image column is mapped and also listed in context_columns; each output row is billed at a higher rate.
  - `creditMultiplier` number: 10 credits per 100 output rows when multimodalPricingApplied is true. Omitted for text-only pricing.

## Other responses

- `400`: Validation failed: column_mapping shape error; a translate, localize or language_expansion failure (unknown ISO 639-1 code, unsupported country/language pair, or a malformed spec); an expand that adds no rows or that this dataset cannot run; or language_expansion combined with translate, localize or expand.
- `402`: Insufficient credits
- `409`: Conflict — dataset is already launching, still importing, or row_count not yet available. Poll GET /datasets/{dataset_id}/status until row_count is populated.

## Changes

- **2026-11-03** `d4cf908c19a0`: 4 info
  - added the new optional request property `expand`
  - added the new optional request property `localize`
  - added the new optional request property `translate`
  - request property `language_expansion` deprecated
- **2026-09-23** `63f15f5fec7b`: 1 info
  - endpoint added

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