---
title: "Add localized rows to a dataset"
method: POST
path: "/api/v1/datasets/{dataset_id}/localize"
tags: ["Dataset"]
---

# Add localized rows to a dataset

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

## Request

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

Adapts a sample of this dataset’s rows to each country/language pair — translating the text and matching that country’s conventions — and returns the result as a new dataset, leaving this one unchanged. The new dataset carries this dataset’s rows alongside the localized ones. Poll GET /datasets/{dataset_id}/status on the returned id until it reaches `succeeded`. To translate into a language without targeting a country, use POST /datasets/{dataset_id}/translate. Set estimate=true to price the request without starting a run.

## Path parameters

- `dataset_id` string, required

## Request body

- PublicLocalizeDto
  - `sample_rate` number, required: Fraction of this dataset’s rows to expand, per target. At 0.25 with two targets, a 1,000-row dataset gains 500 rows and the new dataset holds 1,500.
  - `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.
  - `pairs` PublicCountryLanguagePairDto[], required: Target country/language pairs. Each sampled row gains one row localized to each pair — translated into the language and adapted to that country’s conventions. Unsupported combinations are rejected.
    - `country` string, required: ISO 3166-1 alpha-2 country code.
    - `language` string, required: Language code, as ISO 639-1 — optionally with a script subtag. Supported pairs include codes that are not two letters (`zh-Hant` for Taiwan, `yue` for Hong Kong), so the length is not pinned at two here. Membership is decided against the supported-pair list, which names an unsupported entry in its own 400.

## Response `200`

- PublicExpandResponseDto
  - `dataset_id` string, nullable, required: The expanded dataset. It carries this dataset’s rows plus the new 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 expanded 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.
  - `estimated_credits_consumed` number, required: Credits this run consumes, charged against the rows it adds. Zero on an idempotent replay: the earlier run reserved the credits, and this call charges nothing.
  - `estimate` boolean, required: Whether this was an estimate-only request (no run started).
  - `estimated_new_rows` number, required: Rows this run adds, which is what the credit cost is charged against. Zero on an idempotent replay, which adds none.

## Other responses

- `400`: Validation failed: an unsupported country/language pair, a dataset containing images, a dataset with no prompt or completion column, or a request that would add no rows.
- `402`: Insufficient credits
- `409`: Conflict — the dataset is not ready (poll GET /datasets/{dataset_id}/status until it is), or another request holds this idempotency_key and left no run behind, in which case retry with the same key.

## Changes

- **2026-11-03** `d4cf908c19a0`: 1 breaking
  - the `pairs` request property's minItems was increased to `1`

[Operation history](https://skmtc.dev/adaptionlabs/apis/adaption-api/changes/api/v1/datasets/:dataset_id/localize/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)