## Start an augmentation run (or estimate cost)

`datasets.run(strdataset_id, DatasetRunParams**kwargs)  -> DatasetRunResponse`

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

### Parameters

- `dataset_id: str`

- `brand_controls: Optional[BrandControls]`

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

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

    - `"minimal"`

    - `"concise"`

    - `"detailed"`

    - `"extensive"`

  - `safety_categories: Optional[SequenceNotStr[str]]`

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

- `column_mapping: Optional[ColumnMapping]`

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

  - `prompt: str`

    Column to use as the prompt/instruction field

  - `chat: Optional[str]`

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

  - `completion: Optional[str]`

    Column to use as the completion/response field

  - `context: Optional[SequenceNotStr[str]]`

    Columns to include as 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

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

    - `preference_pairs: Optional[bool]`

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

    - `prompt_metadata_injection: Optional[bool]`

      Inject context and constraints into prompts

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

### Returns

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

  - `run_id: Optional[str]`

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

### Example

```python
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)
```

#### Response

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