---
title: "Subsample Dataset"
method: POST
path: "/v1/data-editing/subsample"
tags: ["data-editing"]
---

# Subsample Dataset

`POST /v1/data-editing/subsample`

## Request

- Base URL: `https://api.pioneer.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pioneer.ai/v1/data-editing/subsample`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/pioneer/apis/brain-api/docs/v1/data-editing/subsample/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a subsample of the dataset using random or balanced sampling.

Creates a new dataset version with the subsampled data.

## Request body

- DataEditingSubsampleRequest: Request to subsample a dataset
  - `dataset_name` string, required: Dataset name
  - `version` string, nullable: Dataset version (latest if omitted)
  - `method` 'random' | 'balanced' | 'stratified': Subsampling method
  - `n` integer, required: Target number of rows for the whole result, not per class. For balanced and stratified methods the sample reaches this total whenever the class sizes allow; when they do not, the response carries a warning and the per-class counts achieved.
  - `label_column` string, nullable: Column for balanced/stratified sampling
  - `seed` integer, nullable: Random seed for reproducibility
  - `new_dataset_name` string, nullable: Name for the new subsampled dataset (auto-generated if omitted)

## Response `200`

Successful Response

- DataEditingSubsampleResponse: Response after subsampling
  - `success` boolean, required
  - `dataset_name` string, required
  - `dataset_version` string, required
  - `new_dataset_name` string, required
  - `new_dataset_version` string, required
  - `original_rows` integer, required
  - `new_rows` integer, required
  - `method` string, required
  - `message` string, required
  - `rows_per_class` object, nullable: Rows actually drawn per class label, for the balanced and stratified methods. Null for random sampling, which has no class dimension.
  - `warning` string, nullable: Set when the result could not match the request — for example a class too small to supply its share. A subsample that under-delivers must say so here rather than returning success with an unchanged dataset.

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-24** `0e5e86e2bae5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pioneer/apis/brain-api/changes/v1/data-editing/subsample/post.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) - [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/0e5e86e2bae5?raw)