> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiteml.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dataset augmentations: create, poll, and download runs

> Generate augmented robotics datasets programmatically — point Kite at a dataset, describe the change, and get back a ready-to-train Parquet dataset.

An **augmentation** takes an existing robotics dataset and produces new episodes with a visual change you describe in plain language — a different table surface, new lighting, a swapped background. You give Kite four things; it generates the episodes on its GPUs, streams you progress, and delivers a standard LeRobot dataset.

## See it in action

Here is one real demonstration — a bimanual toast-plating task — re-rendered by Augment from a single instruction. Every camera of the episode is transformed together, and the robot's motion and joint trajectories are preserved unchanged. Only the scene changes.

<div className="kite-prompt">
  <span className="kite-prompt__label">Prompt</span>
  <span className="kite-prompt__text">"Replace the white tabletop with warm walnut wood, keep the same lighting and objects."</span>
</div>

<Tabs>
  <Tab title="Left">
    <div className="kite-vs">
      <div className="kite-vs__panel">
        <span className="kite-vs__label">Original</span>

        <video src="https://mintcdn.com/kite-ml/I0tCVEITbvGGR9iI/videos/augment/input_cam_left_high.mp4?fit=max&auto=format&n=I0tCVEITbvGGR9iI&q=85&s=cc7b20f196103eda347548425a8ba3aa" autoPlay loop muted playsInline preload="metadata" data-path="videos/augment/input_cam_left_high.mp4" />
      </div>

      <div className="kite-vs__panel">
        <span className="kite-vs__label kite-vs__label--after">Augmented</span>

        <video src="https://mintcdn.com/kite-ml/I0tCVEITbvGGR9iI/videos/augment/output_cam_left_high.mp4?fit=max&auto=format&n=I0tCVEITbvGGR9iI&q=85&s=64f404dbd91637c71809c623a5d5d48d" autoPlay loop muted playsInline preload="metadata" data-path="videos/augment/output_cam_left_high.mp4" />
      </div>
    </div>
  </Tab>

  <Tab title="Right">
    <div className="kite-vs">
      <div className="kite-vs__panel">
        <span className="kite-vs__label">Original</span>

        <video src="https://mintcdn.com/kite-ml/I0tCVEITbvGGR9iI/videos/augment/input_cam_right_high.mp4?fit=max&auto=format&n=I0tCVEITbvGGR9iI&q=85&s=18d98825f80bf8d3e5f574c05bb60c68" autoPlay loop muted playsInline preload="metadata" data-path="videos/augment/input_cam_right_high.mp4" />
      </div>

      <div className="kite-vs__panel">
        <span className="kite-vs__label kite-vs__label--after">Augmented</span>

        <video src="https://mintcdn.com/kite-ml/I0tCVEITbvGGR9iI/videos/augment/output_cam_right_high.mp4?fit=max&auto=format&n=I0tCVEITbvGGR9iI&q=85&s=b5dd1ee21807bec55041fb8452493440" autoPlay loop muted playsInline preload="metadata" data-path="videos/augment/output_cam_right_high.mp4" />
      </div>
    </div>
  </Tab>

  <Tab title="Left wrist">
    <div className="kite-vs">
      <div className="kite-vs__panel">
        <span className="kite-vs__label">Original</span>

        <video src="https://mintcdn.com/kite-ml/I0tCVEITbvGGR9iI/videos/augment/input_cam_left_wrist.mp4?fit=max&auto=format&n=I0tCVEITbvGGR9iI&q=85&s=46c20e4eaeb0b56459e2e55deb7a0b40" autoPlay loop muted playsInline preload="metadata" data-path="videos/augment/input_cam_left_wrist.mp4" />
      </div>

      <div className="kite-vs__panel">
        <span className="kite-vs__label kite-vs__label--after">Augmented</span>

        <video src="https://mintcdn.com/kite-ml/I0tCVEITbvGGR9iI/videos/augment/output_cam_left_wrist.mp4?fit=max&auto=format&n=I0tCVEITbvGGR9iI&q=85&s=38e5995d2b59739e97c34f918f086725" autoPlay loop muted playsInline preload="metadata" data-path="videos/augment/output_cam_left_wrist.mp4" />
      </div>
    </div>
  </Tab>

  <Tab title="Right wrist">
    <div className="kite-vs">
      <div className="kite-vs__panel">
        <span className="kite-vs__label">Original</span>

        <video src="https://mintcdn.com/kite-ml/I0tCVEITbvGGR9iI/videos/augment/input_cam_right_wrist.mp4?fit=max&auto=format&n=I0tCVEITbvGGR9iI&q=85&s=4fdd27b677e9c670c45c12c03c88b6fb" autoPlay loop muted playsInline preload="metadata" data-path="videos/augment/input_cam_right_wrist.mp4" />
      </div>

      <div className="kite-vs__panel">
        <span className="kite-vs__label kite-vs__label--after">Augmented</span>

        <video src="https://mintcdn.com/kite-ml/I0tCVEITbvGGR9iI/videos/augment/output_cam_right_wrist.mp4?fit=max&auto=format&n=I0tCVEITbvGGR9iI&q=85&s=33d5e3bfdbe0dfdbbb0328bb20efa294" autoPlay loop muted playsInline preload="metadata" data-path="videos/augment/output_cam_right_wrist.mp4" />
      </div>
    </div>
  </Tab>
</Tabs>

<p className="kite-vs__caption">Original teleoperation capture versus the Augment render — same frame, same motion, new environment. One prompt produced all four camera views, each with matching joint trajectories ready to train on.</p>

## Create a run

One call starts a run. Give it the source dataset, your instructions, the episode count, and where the results should go.

```bash theme={"system"}
curl -X POST https://api.kiteml.com/v1/augmentations \
  -H "Authorization: Bearer $KITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "repo_id": "lerobot/pusht" },
    "instructions": "change the table surface to white marble, vary the lighting",
    "config": { "episode_count": 100 },
    "output": { "type": "download" }
  }'
```

### Request body

<ParamField body="source.repo_id" type="string" required>
  The Hugging Face LeRobot dataset to augment, e.g. `lerobot/pusht`.
</ParamField>

<ParamField body="instructions" type="string" required>
  Plain-language description of the visual change to apply to every episode.
</ParamField>

<ParamField body="config.episode_count" type="integer" required>
  Number of augmented episodes to generate. Must be between `1` and `50`.
</ParamField>

<ParamField body="output.type" type="string" required>
  Where results are delivered. `download` keeps them on Kite for you to fetch; `huggingface` pushes the finished dataset to your account.
</ParamField>

<ParamField body="output.repo_id" type="string">
  Required when `output.type` is `huggingface` — the destination repo, e.g. `your-org/pusht-marble`.
</ParamField>

The call returns the augmentation resource, including its `id`, immediately:

```json Response — 202 Accepted theme={"system"}
{
  "id": "aug_01J8X4M2K9ZQ6R7T3V5W8Y0B1C",
  "object": "augmentation",
  "status": "queued",
  "progress": 0.0,
  "output": { "type": "download" },
  "created_at": "2026-07-21T09:14:00Z"
}
```

Common failures at create time:

* `400 parameter_invalid` — a malformed field, named in `param`
* `400 episode_limit_exceeded` — `episode_count` above 50
* `402 insufficient_tokens` — not enough credits
* `400 huggingface_not_connected` — for `huggingface` output, when you haven't linked a Hugging Face token in the dashboard

See [Authentication → Errors](/platform-api/authentication#errors) for the envelope.

### Idempotency

Pass a unique `Idempotency-Key` header to make retries safe. A repeated request with the same key returns the original run instead of starting a duplicate — so a dropped connection or a CI retry never double-charges you.

```bash theme={"system"}
curl -X POST https://api.kiteml.com/v1/augmentations \
  -H "Authorization: Bearer $KITE_API_KEY" \
  -H "Idempotency-Key: 9f1c8e2a-run-42" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "repo_id": "lerobot/pusht" }, "instructions": "...", "config": { "episode_count": 100 }, "output": { "type": "download" } }'
```

<Note>
  Reusing a key with a *different* payload returns `409 Conflict` — the key is bound to the first request body it saw.
</Note>

## Track progress

Episodes are generated and saved incrementally. Poll the run to watch it move through its lifecycle, with a live `progress` value and a human-readable `status_message`.

```bash theme={"system"}
curl https://api.kiteml.com/v1/augmentations/aug_01J8X4... \
  -H "Authorization: Bearer $KITE_API_KEY"
```

```json theme={"system"}
{
  "id": "aug_01J8X4M2K9ZQ6R7T3V5W8Y0B1C",
  "object": "augmentation",
  "status": "processing",
  "progress": 0.42,
  "status_message": "Generated 42 of 100 videos"
}
```

The `status` field moves through:

| Status       | Meaning                                                  |
| ------------ | -------------------------------------------------------- |
| `queued`     | Accepted, waiting for a GPU slot                         |
| `processing` | Episodes are being generated                             |
| `succeeded`  | All episodes generated; output is ready                  |
| `failed`     | The run stopped before completing (see `status_message`) |
| `canceled`   | You canceled the run                                     |

<Tip>
  Poll on an interval of a few seconds. Episodes are saved as they finish, so a long run's `progress` moves steadily rather than jumping at the end.
</Tip>

## Get your dataset

When `status` is `succeeded`, a `download` run exposes its files under `output.files`. Fetch each one, preserving its `path`, to reconstruct a standard LeRobot Parquet dataset on disk.

```json Response — output.files theme={"system"}
"output": {
  "type": "download",
  "files": [
    { "path": "meta/info.json",                 "bytes": 3186,  "url": "https://..." },
    { "path": "data/chunk-000/file-000.parquet", "bytes": 16457, "url": "https://..." },
    { "path": "videos/chunk-000/observation.images.cam/episode_000000.mp4", "url": "https://..." }
  ]
}
```

The `kite augment download` CLI command does this for you — see the [CLI docs](https://kiteml.com/docs/cli). If you chose `huggingface` output instead, `output.url` links the dataset pushed to your account.

<Note>
  Each `url` is either a short-lived signed storage URL or an authenticated `/v1/augmentations/:id/files/:path` proxy path. Send your `Authorization` header when fetching and handle both — the proxy path needs the key; the signed URL ignores it.
</Note>

<Check>
  The result is a standard **LeRobot v3.0** dataset: Parquet tables for states and actions plus MP4 camera video. It's the same format Kite training accepts, so you can train on it with no conversion. No proprietary output format, no lock-in.
</Check>

## Cancel a run

Stop a queued or processing run at any time. You're only billed for episodes generated before cancellation.

```bash theme={"system"}
curl -X POST https://api.kiteml.com/v1/augmentations/aug_01J8X4.../cancel \
  -H "Authorization: Bearer $KITE_API_KEY"
```