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

### Path Parameters

- `dataset_id: string`

### Body Parameters

- `brand_controls: optional object { hallucination_mitigation, length, safety_categories }`

  Brand and quality controls for generated completions (length, safety, hallucination grounding).

  - `hallucination_mitigation: optional boolean`

    Enable web-search grounding to reduce hallucinations in generated completions

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

    Target response length. Controls verbosity of generated completions.

    - `"minimal"`

    - `"concise"`

    - `"detailed"`

    - `"extensive"`

  - `safety_categories: optional array of string`

    Content safety categories to enforce. Completions violating these are filtered.

- `column_mapping: optional object { prompt, chat, completion, context }`

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

  - `prompt: string`

    Column to use as the prompt/instruction field

  - `chat: optional string`

    Column containing chat/conversation data (alternative to prompt+completion)

  - `completion: optional string`

    Column to use as the completion/response field

  - `context: optional array of string`

    Columns to include as context

- `estimate: optional boolean`

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

- `job_specification: optional object { idempotency_key, max_rows }`

  Job execution parameters

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

  - `max_rows: optional number`

    Maximum number of rows to process in this run

- `recipe_specification: optional object { recipes, version }`

  Augmentation recipe configuration. Omitted recipes use backend defaults.

  - `recipes: optional object { deduplication, preference_pairs, prompt_metadata_injection, 2 more }`

    Augmentation recipe toggles. Omitted recipes use backend defaults.

    - `deduplication: optional boolean`

      Remove near-duplicate rows

    - `preference_pairs: optional boolean`

      Generate DPO-style preference pairs (chosen/rejected) instead of instruction completions

    - `prompt_metadata_injection: optional boolean`

      Inject context and constraints into prompts

    - `prompt_rephrase: optional boolean`

      Rephrase prompts for variety and clarity

    - `reasoning_traces: optional boolean`

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

  - `version: optional string`

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

### Returns

- `estimate: boolean`

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

- `estimatedCreditsConsumed: number`

  Estimated number of credits that will be consumed by this run

- `estimatedMinutes: number`

  Estimated processing time in minutes

- `run_id: optional string`

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

### Example

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

#### Response

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