---
title: "generate more rows"
method: POST
path: "/datasets/{id}/rows/build"
tags: ["Datasets"]
---

# generate more rows

`POST /datasets/{id}/rows/build`

## Request

- Base URL: `https://api.riveterhq.com/v1`
- URL: `https://api.riveterhq.com/v1/datasets/{id}/rows/build`
- Auth: HTTP bearer

Ask the list generator for `count` more rows of an existing dataset. Requires a `index_column` on the dataset (set one with [PATCH /datasets/{id}](#tag/dataset-crud/patch/datasets/{id})); the generator is told the existing rows and skips them, and anything it still repeats is dropped on the index column. `prompt` says what to find; when omitted, the prompt of the dataset's latest build is reused. The generator may find fewer rows than `count`: when the run finishes, its `progress` reports `requested_rows`, `generated_rows`, `added_rows`, `skipped_duplicate_rows`. `auto_fill: true` fills the new rows' output columns when they land (a second paid run). The response is the dataset plus `run` (the generation run); poll it with [GET /runs/{id}](#tag/runs/get/runs/{id}) or pass `webhook_url`.

## Path parameters

- `id` string, required

## Request body

- object
  - `prompt` string: What the rows are. Default: the prompt of the dataset's latest build.
  - `count` integer, required: How many rows to generate. Capped per account.
  - `budget` number: Most credits the build may spend (default 50 + 1.5 per row). A deposit of the expected spend is charged at kickoff; the rest is charged as it runs, up to this budget. A low budget means fewer rows.
  - `auto_fill` boolean: Fill the new rows' output columns when they land (needs an enrichment on the dataset)
  - `webhook_url` string, uri: POSTed the generation run when it finishes
  - `fill_webhook_url` string, uri: With auto_fill — POSTed the fill run when it finishes
  - `estimate_cost` boolean: Validate and price the request without running or charging anything; the 200 response is the credit estimate (EstimateCostResult).
  - `max_credits` number: Credit ceiling. Refused with 422 credit_cap_exceeded (nothing charged) when the estimate's maximum exceeds it.

## Response `200`

estimate_cost only — the credit estimate; nothing was started

- EstimateCostResult: Returned with `200` when a paid endpoint is called with `estimate_cost: true`. The request was validated and priced; nothing was created or charged.
  - `estimate_cost` true, required
  - `type` 'enrichment' | 'dataset_build' | 'extraction_discovery' | 'extraction' | 'monitor' | 'scrape' | 'quick_search' | 'search_agent', required: What would have been charged for (`monitor` = one scheduled run of the monitor)
  - `credit_detail` CreditDetail, required: The estimate made at kickoff next to what has been charged so far. `estimate` is null for runs started before estimates existed. Estimates and credit errors add `credits_remaining` and `sufficient_credits`.
    - `estimate` CreditEstimate, required: Kickoff-time credit estimate. `maximum` is the contract — the run never charges more. `minimum` is 0 when the run can charge less (cells that short-circuit, a dataset build settling below its cap). `upfront` is the deposit taken at kickoff when `charged_upfront` is true (a dataset build's expected spend; equal to `maximum` for a fixed-price product; 0 for a fill). `expected` is the likely charge when history exists (a dataset fill: rows × the enrichment's average charge per row; a dataset build: equal to `upfront`). `typical` is `{ low, high }` — the recent p25–p75 settled range for builds of that size (absent elsewhere).
      - `minimum` number, required: Least the run can cost
      - `expected` number: Likely cost from past runs of the same config; absent without history
      - `typical` object: Recent p25–p75 settled range for builds of this size; absent without a dataset build estimate
        - `low` number, required
        - `high` number, required
      - `maximum` number, required: Most the run can cost
      - `upfront` number: Credits taken at kickoff when charged_upfront is true; 0 when the charge accrues as work completes
      - `charged_upfront` boolean, required: true when a deposit is taken at kickoff (dataset builds, extractions); false when credits accrue as work completes
    - `credits_used` number, required: Credits charged so far (same value as the top-level credits_used)
    - `credits_remaining` number: Account balance. Only on estimates and credit errors.
    - `sufficient_credits` boolean: Whether the balance covers `estimate.maximum`. Only on estimates and credit errors.

## Other responses

- `201`: The dataset with `run` (the generation run)
- `400`: The request is malformed or names a conflicting parameter combination
- `401`: Missing or invalid API key (`request_status` body — see the AuthError schema)
- `403`: The API key's account may not access this resource or endpoint (`forbidden`), or the account has not migrated to Datasets yet (`feature_not_enabled` — open Datasets in the app and click "Migrate to Datasets")
- `404`: No resource with that id on this account
- `409`: Duplicate run_key or a run already in progress
- `422`: The request is valid but can't be executed (e.g. insufficient_credits, credit_cap_exceeded when max_credits is set, validation failure)

## Changes

- **2026-11-13** `fac56b649559`: 1 warning
  - removed the optional property `allOf[subschema #2]/run/legacy` from the response with the `201` status
- **2026-10-30** `dcb4d45ade1a`: 14 info
  - added the optional property `allOf[subschema #2]/run/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `201` status
  - added the optional property `allOf[subschema #2]/run/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/upfront` to the response with the `201` status
  - added the optional property `credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `200` status
  - added the optional property `credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/upfront` to the response with the `200` status
  - …10 more
- **2026-10-27** `591a7eba392d`: 1 info
  - added the new optional request property `budget`
- **2026-10-26** `246d92c52951`: 1 info
  - added the optional property `allOf[subschema #2]/run/legacy` to the response with the `201` status
- **2026-10-19** `76aabcc5686b`: 2 info
  - api tag `Datasets` added
  - api tag `Datasets (beta)` removed

[Operation history](https://skmtc.dev/riveterhq/apis/riveter-api/changes/datasets/:id/rows/build/post.md)

---

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