Start an augmentation run (or estimate cost)

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

Validates column mapping and recipe configuration, reserves credits, and starts the augmentation pipeline. 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

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.

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.

hallucination_mitigation: Optional[bool]

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

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[SequenceNotStr[str]]

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

column_mapping: Optional[ColumnMapping]

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

chat: Optional[str]

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

completion: Optional[str]

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

context: Optional[SequenceNotStr[str]]

Columns to include as context. Optional in prompt mode; required (at least one entry) in universal-prompt mode; not allowed in chat mode.

image: Optional[str]

Column containing per-row images (URLs, file paths, or encoded bytes) to fold into the augmentation 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.

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.

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.

estimate: Optional[bool]

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

job_specification: Optional[JobSpecification]

Job execution parameters

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.

max_rows: Optional[float]

Maximum number of rows to process in this run

minimum1

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.

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

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[SequenceNotStr[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.

minLength2

maxLength2

language: str

ISO 639-1 language code.

minLength2

maxLength2

recipe_specification: Optional[RecipeSpecification]

Augmentation recipe configuration. Omitted recipes use backend defaults.

recipes: Optional[RecipeSpecificationRecipes]

Augmentation recipe toggles. Omitted recipes use backend defaults.

deduplication: Optional[bool]

Remove near-duplicate rows

prompt_rephrase: Optional[bool]

Rephrase prompts for variety and clarity

reasoning_traces: Optional[bool]

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

version: Optional[str]

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

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 augmentation pipeline.

One of the following:

"instruction_dataset"

"preference_pairs"

ReturnsExpand Collapse

class DatasetRunResponse: …

estimate: bool

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

estimated_credits_consumed: float

Estimated number of credits that will be consumed by this run

estimated_minutes: float

Estimated processing time in minutes

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.

run_id: Optional[str]

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

Start an augmentation 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)

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

Returns Examples

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