Start an adaptation run (or estimate cost)

POST/api/v1/datasets/{dataset_id}/run

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

ParametersExpand Collapse

dataset_id: str

column_mapping: Optional[ColumnMapping]

Column role assignments for adaptation. Required for real runs, optional for estimate-only requests.

prompt: Optional[str]

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: Optional[str]

Column to use as the completion/response field. Optional in prompt mode and universal-prompt mode; not allowed in chat mode.

chat: Optional[str]

Column containing chat/conversation data. Chat mode is exclusive — when chat is set, all other column-mapping fields must be omitted.

context: Optional[Sequence[str]]

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: Optional[str]

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 at least one entry in context.

image: Optional[str]

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: Optional[RecipeSpecification]

Adaptation recipe configuration. Omitted recipes use backend defaults.

version: Optional[str]

Recipe schema version. Allows recipe options to evolve across releases.

recipes: Optional[RecipeSpecificationRecipes]

Adaptation recipe toggles. Omitted recipes use backend defaults.

prompt_rephrase: Optional[bool]

Rephrase prompts for variety and clarity

deduplication: Optional[bool]

Remove near-duplicate rows

reasoning_traces: Optional[bool]

Add reasoning traces (chain-of-thought) to completions

job_specification: Optional[JobSpecification]

Job execution parameters

max_rows: Optional[float]

Maximum number of rows to process in this run

minimum1

idempotency_key: Optional[str]

Client-generated idempotency key for safe retries. If a launch with the same key already exists, the original response is returned.

brand_controls: Optional[BrandControls]

Brand and quality controls for generated completions. Covers response length, content safety categories, web-search grounding, and a freeform blueprint system prompt.

length: Optional[Literal["minimal", "concise", "detailed", "extensive"]]

Target response length. Controls verbosity of generated completions.

One of the following:

"minimal"

"concise"

"detailed"

"extensive"

safety_categories: Optional[Sequence[str]]

Content safety categories to enforce. Completions violating any listed category are filtered from the output.

hallucination_mitigation: Optional[bool]

Enable web-search grounding to reduce hallucinations in generated completions.

blueprint: Optional[str]

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: Optional[Literal["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.

One of the following:

"instruction_dataset"

"preference_pairs"

estimate: Optional[bool]

When true, validates the request and returns the estimated credit cost without starting a run.

language_expansion: Optional[LanguageExpansion]

Translation/localization expansion. When set, the pipeline produces additional rows in the requested languages or country/language variants. Output row count ≈ input × (1 + sample_rate × target_count); credits are billed on output rows.

Three-state field:

omitted — leaves any prior expansion config on the dataset unchanged (no-op). A wizard-saved expansion is preserved across SDK-driven /run calls that do not pass language_expansion.
language_expansion: null — explicitly clears any prior expansion config on this dataset (overrides wizard state).
object — overwrites the prior expansion config with the given spec.

type: Literal["translate", "localize"]

Expansion mode. translate produces one new row variant per target language; localize produces one new row variant per country/language pair.

One of the following:

"translate"

"localize"

languages: Optional[Sequence[str]]

Target ISO 639-1 language codes (required when type=translate, forbidden when type=localize). Validated against the supported language list at request time; unknown values return 400 with a sample of supported codes.

pairs: Optional[Iterable[LanguageExpansionPair]]

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: str

ISO 3166-1 alpha-2 country code.

language: str

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: float

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.

minimum0.01

maximum1

ReturnsExpand Collapse

class DatasetRunResponse: …

run_id: Optional[str]

Unique identifier for this pipeline run. Null for estimate-only requests.

estimated_minutes: float

Estimated processing time in minutes

estimated_credits_consumed: float

Estimated number of credits that will be consumed by this run

estimate: bool

Whether this was an estimate-only request (no run started)

multimodal_pricing_applied: bool

True when an image column is mapped and also listed in context_columns; each output row is billed at a higher rate.

credit_multiplier: Optional[float]

10 credits per 100 output rows when multimodalPricingApplied is true. Omitted for text-only pricing.

Start an adaptation run (or estimate cost)

import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
response = client.datasets.run(
    dataset_id="dataset_id",
)
print(response.run_id)

{
  "run_id": "dataset-550e8400-e29b-41d4-a716-446655440000-1712234567890",
  "estimatedMinutes": 0,
  "estimatedCreditsConsumed": 0,
  "estimate": true,
  "multimodalPricingApplied": true,
  "creditMultiplier": 0
}

Returns Examples

{
  "run_id": "dataset-550e8400-e29b-41d4-a716-446655440000-1712234567890",
  "estimatedMinutes": 0,
  "estimatedCreditsConsumed": 0,
  "estimate": true,
  "multimodalPricingApplied": true,
  "creditMultiplier": 0
}