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

Path ParametersExpand Collapse

dataset_id: string

Body ParametersJSONExpand Collapse

column_mapping: optional object { prompt, completion, chat, 3 more }

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

prompt: optional 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: optional string

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

chat: optional string

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

context: optional array of 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: optional 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 at least one entry in context.

image: optional string

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.

recipe_specification: optional object { version, recipes }

Augmentation recipe configuration. Omitted recipes use backend defaults.

version: optional string

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

recipes: optional object { prompt_rephrase, deduplication, reasoning_traces }

Augmentation recipe toggles. Omitted recipes use backend defaults.

prompt_rephrase: optional boolean

Rephrase prompts for variety and clarity

deduplication: optional boolean

Remove near-duplicate rows

reasoning_traces: optional boolean

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

job_specification: optional object { max_rows, idempotency_key }

Job execution parameters

max_rows: optional number

Maximum number of rows to process in this run

minimum1

idempotency_key: optional string

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

brand_controls: optional object { length, safety_categories, hallucination_mitigation, blueprint }

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

length: optional "minimal" or "concise" or "detailed" or "extensive"

Target response length. Controls verbosity of generated completions.

One of the following:

"minimal"

"concise"

"detailed"

"extensive"

safety_categories: optional array of string

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

hallucination_mitigation: optional boolean

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

blueprint: optional 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: optional "instruction_dataset" or "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"

estimate: optional boolean

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

language_expansion: optional object { type, languages, pairs, sample_rate }

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: "translate" or "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 array of string

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 array of object { country, language }

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

ISO 3166-1 alpha-2 country code.

language: string

ISO 639-1 language code.

sample_rate: number

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

run_id: optional string

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

estimatedMinutes: number

Estimated processing time in minutes

estimatedCreditsConsumed: number

Estimated number of credits that will be consumed by this run

estimate: boolean

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

multimodalPricingApplied: boolean

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

creditMultiplier: optional number

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

Start an augmentation run (or estimate cost)

curl https://api.prod.adaptionlabs.ai/api/v1/datasets/$DATASET_ID/run \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ADAPTION_API_KEY" \
    -d '{
          "training_type": "instruction_dataset"
        }'

{
  "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
}