# Combine

## Combine multiple Datasets into a single new merged Dataset

`datasets.combine.create(CombineCreateParams**kwargs)  -> CombineCreateResponse`

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

### Parameters

- `dataset_ids: Sequence[str]`

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

- `name: str`

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

### Returns

- `CombineCreateResponse`

  - `class CombineResponseDto: …`

    - `dataset_id: str`

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

  - `class CombineJobResponseDto: …`

    - `combine_job_id: str`

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

    - `status: Literal["queued", "running", "succeeded", "failed"]`

      Current background combine job status.

      - `"queued"`

      - `"running"`

      - `"succeeded"`

      - `"failed"`

    - `dataset_id: Optional[object]`

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

    - `error_message: Optional[object]`

      Customer-safe failure message when the background combine fails.

### 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
)
combine = client.datasets.combine.create(
    dataset_ids=["string", "string"],
    name="name",
)
print(combine)
```

#### Response

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

## Validate that a set of Datasets can be combined

`datasets.combine.validate(CombineValidateParams**kwargs)`

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

Synchronous compatibility check. Returns a single `issues` array containing both blockers (`level: "error"`) and reconcilable concerns (`level: "warning"`). `compatible: false` means at least one error-level issue is present (cardinality, ownership, status, run_id). Warning-level entries — column-type mismatches, DPO sources missing ranked generations — are non-blocking; the merge resolves them automatically (mixed types downgrade to instruction_dataset, type mismatches CAST to a common type, etc.). Nothing is written.

### Parameters

- `dataset_ids: Sequence[str]`

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

### 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
)
client.datasets.combine.validate(
    dataset_ids=["string", "string"],
)
```

## Domain Types

### Combine Create Response

- `CombineCreateResponse`

  - `class CombineResponseDto: …`

    - `dataset_id: str`

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

  - `class CombineJobResponseDto: …`

    - `combine_job_id: str`

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

    - `status: Literal["queued", "running", "succeeded", "failed"]`

      Current background combine job status.

      - `"queued"`

      - `"running"`

      - `"succeeded"`

      - `"failed"`

    - `dataset_id: Optional[object]`

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

    - `error_message: Optional[object]`

      Customer-safe failure message when the background combine fails.

# Jobs

## Get the status of a background dataset combine job

`datasets.combine.jobs.get(strcombine_job_id)  -> JobGetResponse`

**get** `/api/v1/datasets/combine/jobs/{combine_job_id}`

Returns the lifecycle state for an async combine request. This state is separate from Dataset.status; `dataset_id` is populated only after the output Dataset has been created.

### Parameters

- `combine_job_id: str`

### Returns

- `class JobGetResponse: …`

  - `combine_job_id: str`

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

  - `status: Literal["queued", "running", "succeeded", "failed"]`

    Current background combine job status.

    - `"queued"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

  - `dataset_id: Optional[object]`

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

  - `error_message: Optional[object]`

    Customer-safe failure message when the background combine fails.

### 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
)
job = client.datasets.combine.jobs.get(
    "combine_job_id",
)
print(job.combine_job_id)
```

#### Response

```json
{
  "combine_job_id": "combine_job_id",
  "status": "queued",
  "dataset_id": {},
  "error_message": {}
}
```

## Domain Types

### Job Get Response

- `class JobGetResponse: …`

  - `combine_job_id: str`

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

  - `status: Literal["queued", "running", "succeeded", "failed"]`

    Current background combine job status.

    - `"queued"`

    - `"running"`

    - `"succeeded"`

    - `"failed"`

  - `dataset_id: Optional[object]`

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

  - `error_message: Optional[object]`

    Customer-safe failure message when the background combine fails.