## Combine multiple Datasets into a single new merged Dataset

**post** `/api/v1/datasets/combine`

Requires an Idempotency-Key header to dedupe double-submits. Returns the merged Dataset synchronously by default. When async combine is enabled, clients may send `Prefer: respond-async` to receive a background job handle.

### Body Parameters

- `dataset_ids: array of string`

  Source Dataset IDs to combine. Must all belong to the caller’s org and be in a combinable state.

- `name: string`

  User-supplied name for the merged Dataset. Surfaced in the dataset list.

### Returns

- `CombineResponseDto object { dataset_id }`

  - `dataset_id: string`

    The newly created merged Dataset’s ID. Returns existing ID on idempotent replay.

- `CombineJobResponseDto object { combine_job_id, status, dataset_id, error_message }`

  - `combine_job_id: string`

    Background combine job ID. Poll the combine job status endpoint until it succeeds or fails.

  - `status: "queued" or "running" or "succeeded" or "failed"`

    Current background combine job status.

    - `"queued"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

  - `dataset_id: unknown`

    The merged Dataset ID. Null until the background combine succeeds.

  - `error_message: unknown`

    Customer-safe failure message when the background combine fails.

### Example

```http
curl https://api.prod.adaptionlabs.ai/api/v1/datasets/combine \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ADAPTION_API_KEY" \
    -d '{
          "dataset_ids": [
            "string",
            "string"
          ],
          "name": "name"
        }'
```

#### Response

```json
{
  "dataset_id": "dataset_id"
}
```