---
title: "Add rows to a dataset from the curated pool"
method: POST
path: "/api/v1/datasets/{dataset_id}/augment"
tags: ["Dataset"]
---

# Add rows to a dataset from the curated pool

`POST /api/v1/datasets/{dataset_id}/augment`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/adaptionlabs/apis/adaption-api/docs/api/v1/datasets/:dataset_id/augment/post.ts> (a function with typed inputs; its response is checked against the schema)

Retrieves additional rows matching this dataset and returns them as a new dataset, leaving this one unchanged. The new dataset carries this dataset’s rows alongside the retrieved ones, so it can be trained on or downloaded directly. Omit both row counts to receive the recommended fill and its cost as a quote; a run needs explicit row counts, or fill_to_recommended=true to fill any count you leave out with its recommended value. Poll GET /datasets/{dataset_id}/status on the returned id until it reaches `succeeded`. Set estimate=true to price the request without starting a run.

## Path parameters

- `dataset_id` string, required

## Request body

- PublicAugmentDto
  - `domain_rows` number: How many additional rows to retrieve from topics matching this dataset. Omit domain_rows and general_rows to receive the recommended fill and its cost as a quote; a run needs a count, or fill_to_recommended=true.
  - `general_rows` number: How many additional rows to retrieve from other topics, to broaden the dataset. Omit domain_rows and general_rows to receive the recommended fill and its cost as a quote; a run needs a count, or fill_to_recommended=true.
  - `similar_rows` number: How many new rows to generate in the style of this dataset. A sample of its rows is analysed for topic, language and prompt/completion conventions, and new rows are generated to match. Combines with domain_rows and general_rows in one run, and is never filled from the recommendation. Naming it makes the request explicit rather than a quote. Defaults to 0.
  - `fill_to_recommended` boolean: When true, fills every count you leave out (domain_rows, general_rows) with its recommended value; a count you name is used as given. Omit every count (including similar_rows) and leave this false to receive the recommended fill as a quote instead.
  - `training_type` 'instruction_dataset' | 'preference_pairs': Shape of the rows to retrieve. `instruction_dataset` (default) retrieves prompt/completion pairs for SFT; `preference_pairs` retrieves chosen/rejected pairs for DPO.
  - `estimate` boolean: When true, validates the request and returns the estimated credit cost without starting a run or creating a dataset.
  - `idempotency_key` string: Opaque key that makes a retried request safe. A second request carrying the same key returns the dataset the first one created instead of starting and charging for a second run.

## Response `200`

- PublicAugmentResponseDto
  - `dataset_id` string, nullable, required: The augmented dataset. It carries this dataset’s rows plus the retrieved ones, and is ready to download once its status reaches `succeeded`. Null for an estimate, which creates nothing.
  - `status` 'pending' | 'running' | 'awaiting_input' | 'succeeded' | 'failed', nullable, required: Status of the augmented dataset at the moment this response was sent, in the same vocabulary GET /datasets/{dataset_id}/status reports. Poll that endpoint until it reaches `succeeded` or `failed`. An idempotent replay of a finished run returns its terminal status here.
  - `domain_rows` number, required: Rows this run retrieves from topics matching the dataset, or the recommended fill an estimate priced.
  - `general_rows` number, required: Rows this run retrieves from other topics, to broaden the dataset, or the recommended fill an estimate priced.
  - `estimated_credits_consumed` number, required: Credits this run consumes, charged against the requested rows.
  - `estimate` boolean, required: Whether this was an estimate-only request (no run started).

## Other responses

- `400`: Validation failed: the recommended fill has nothing to add, the dataset contains images (the pool is text-only), or its topic mix cannot be determined (domain_rows / general_rows only). A request that named no row counts also gets 400, with the recommended fill and its cost as a quote in the body.
- `402`: Insufficient credits
- `409`: Conflict — the dataset is not ready. Poll GET /datasets/{dataset_id}/status until it is.

## Changes

- **2026-10-20** `7398ff1eeeba`: 5 info
  - added the new optional request property `fill_to_recommended`
  - added the new optional request property `similar_rows`
  - added the media type `application/json` for the response with the status `400`
  - added the required property `domain_rows` to the response with the `200` status
  - …1 more

[Operation history](https://skmtc.dev/adaptionlabs/apis/adaption-api/changes/api/v1/datasets/:dataset_id/augment/post.md)

---

[API](https://skmtc.dev/adaptionlabs/apis/adaption-api.md) - [All operations](https://skmtc.dev/adaptionlabs/apis/adaption-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adaptionlabs/apis/adaption-api/revisions/d4cf908c19a0?raw)