## Start an augmentation run (or estimate cost)

`client.datasets.run(stringdatasetID, DatasetRunParamsbody, RequestOptionsoptions?): 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

- `datasetID: string`

- `body: DatasetRunParams`

  - `brand_controls?: BrandControls`

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

    - `hallucination_mitigation?: boolean`

      Enable web-search grounding to reduce hallucinations in generated completions

    - `length?: "minimal" | "concise" | "detailed" | "extensive"`

      Target response length. Controls verbosity of generated completions.

      - `"minimal"`

      - `"concise"`

      - `"detailed"`

      - `"extensive"`

    - `safety_categories?: Array<string>`

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

  - `column_mapping?: ColumnMapping`

    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?: string`

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

    - `completion?: string`

      Column to use as the completion/response field

    - `context?: Array<string>`

      Columns to include as context

  - `estimate?: boolean`

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

  - `job_specification?: JobSpecification`

    Job execution parameters

    - `idempotency_key?: string`

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

    - `max_rows?: number`

      Maximum number of rows to process in this run

  - `recipe_specification?: RecipeSpecification`

    Augmentation recipe configuration. Omitted recipes use backend defaults.

    - `recipes?: Recipes`

      Augmentation recipe toggles. Omitted recipes use backend defaults.

      - `deduplication?: boolean`

        Remove near-duplicate rows

      - `preference_pairs?: boolean`

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

      - `prompt_metadata_injection?: boolean`

        Inject context and constraints into prompts

      - `prompt_rephrase?: boolean`

        Rephrase prompts for variety and clarity

      - `reasoning_traces?: boolean`

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

    - `version?: string`

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

### Returns

- `DatasetRunResponse`

  - `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?: string | null`

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

### Example

```typescript
import Adaption from 'adaption';

const client = new Adaption({
  apiKey: process.env['ADAPTION_API_KEY'], // This is the default and can be omitted
});

const response = await client.datasets.run('dataset_id');

console.log(response.run_id);
```

#### Response

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