Riveter

delete rows Datasets beta, per account (else 403 `feature_not_enabled`). Remove rows: `ids` (comma-separated `row_...` ids) and / or `positions` (comma-separated positions from 1), up to 100 rows together. Returns the number deleted.

delete_dataset_rows

enrich Add AI-researched columns to rows. Rows come from exactly one of `input` (columnar: `{ "Header": ["row1", "row2"] }`, all arrays equal length) or `dataset_id` (a completed build, `ds_...`). Column config, exactly one of, in order of preference: 1. `enrichment_id` — run a saved enrichment (`enr_...`, from `list_enrichments`). Fixed, tested config; most consistent. Up to 10,000 rows. Input headers must match the enrichment's input columns (`get_enrichment`). 2. `prompt` + `attributes` — Riveter drafts the column config from a description and up to 20 output column names. No setup; results vary per run. Up to 1,000 rows. 3. `output` — full per-column spec: `prompt`, `contexts`, `tools`, `format`, `run_when`, or a tool-only `tool`. Up to 1,000 rows. Call `help` with `column_config`, `run_when`, `formats`, `tools`, or `examples` before writing one. Returns a run. Poll `get_run_result` with `wait: 50` (or pass `webhook_url`). `dry_run: true` returns the credit estimate without running. **Example — Run a saved enrichment:** { "enrichment_id": "enr_018f5b60-1234-7abc-89ab-0123456789ab", "input": { "Company Name": [ "Acme Corp", "Tech Solutions Inc" ] } } **Example — Prompt + attributes (auto-generated config):** { "prompt": "Research each company", "attributes": [ "CEO", "Employee Count", "Industry" ], "input": { "Company": [ "Apple", "Google" ] }, "webhook_url": "https://your-server.com/webhook" } **Example — Full output specification:** { "output": { "Employee Count": { "prompt": "Find the number of employees at this company", "contexts": [ "Company" ], "format": "number" } }, "input": { "Company": [ "Apple", "Google" ] } } **Example — Enrich the rows of a completed dataset build:** { "enrichment_id": "enr_018f5b60-1234-7abc-89ab-0123456789ab", "dataset_id": "ds_018f6a70-1234-7abc-89ab-0123456789ab" } **Example — Price the run without starting it:** { "enrichment_id": "enr_018f5b60-1234-7abc-89ab-0123456789ab", "input": { "Company Name": [ "Acme Corp", "Tech Solutions Inc" ] }, "dry_run": true } **Workflow:** Starts an async run. Poll `get_run` with the returned run id until status is 'success', then call `get_run_result` for the output.

enrich

enrichment → list build Build a list **shaped for this enrichment**: identifiers are derived from the enrichment's source-data columns automatically, so generated rows land as valid input rows. The build finds rows only; the enrichment's output columns are not researched until the enrichment runs. Optionally set `auto_run_enrichment: true` to run the enrichment on the rows as soon as the build completes (a second paid run; the kickoff response then carries `enrichment_run_id`). Returns the dataset-build run — poll it via [GET /runs/{id}](#tag/runs/get/runs/{id}). **Example — Build rows and auto-run the enrichment:** { "prompt": "US-based fintech startups", "qualifiers": [ "B2B", "founded after 2015" ], "max_items": 100, "auto_run_enrichment": true } **Workflow:** Starts an async dataset build run matching the enrichment's input columns. Poll `get_run`, then fetch rows with `get_run_result`.

build_dataset_for_enrichment

export dataset (CSV, Excel, or JSON Lines) Datasets beta, per account (else 403 `feature_not_enabled`). The dataset as CSV text (or JSON Lines with `output_format: "jsonl"`; `xlsx` is binary and meant for a browser): input columns, then output columns, one line per row. For a few rows prefer `list_dataset_rows` (it carries cell states).

export_dataset

extend list build More deduplicated rows for a completed list build (a build id from `build_dataset` with `max_items`, not a dataset). For a dataset use `build_dataset_rows`. **Workflow:** Starts an async run that adds rows to an existing dataset. Poll `get_run`, then fetch with `get_run_result`.

extend_dataset

generate more rows Datasets beta, per account (else 403 `feature_not_enabled`). Generate `count` more rows for a dataset (paid; `estimate_cost` first). Needs a `index_column` on the dataset (`update_dataset`). `prompt` says what to find (default: the dataset's last build prompt); the generator skips the existing rows and may find fewer than `count` — the finished run's `progress` has `requested_rows`, `generated_rows`, `added_rows`, `skipped_duplicate_rows`. `auto_fill: true` fills them when they land. Returns the dataset and `run`. **Example — Fifty more, filled on arrival:** { "prompt": "Specialty coffee roasters in Oakland and Berkeley", "count": 50, "auto_fill": true }

build_dataset_rows

get extraction The extraction's status and definition. `status` is `discovering` while the agent builds the plan, then `ready` (or `discovery_failed`). Once `ready`, execute with [POST /extractions/{id}/runs](#tag/extractions/post/extractions/{id}/runs).

get_extraction

get monitor The monitor's schedule, webhook, and next run time.

get_monitor

import rows (CSV) Datasets beta, per account (else 403 `feature_not_enabled`). Append rows from CSV text (`csv`; header row = input and / or output column names, output values land as `manual` cells; free). Up to 1,000 rows land at once (`import.status` done); more are accepted and land in the background (`importing`; `get_dataset` shows `import_in_progress`). Duplicates on the index column are skipped.

import_dataset_rows

list datasets Datasets beta, per account (else 403 `feature_not_enabled`). The account's datasets, newest first (up to 200): id, name, column counts, `row_count`, newest run. `get_dataset` has the columns and enrichment.

list_datasets

list enrichments The account's enrichments, newest first: id, name, input / output column names (app-built ones also `status`, `app_url`). Paginate with `page` / `per_page` (max 50); filter by `status` (app-built only), `name`. `get_enrichment` has the columns' config.

list_enrichments

list enrichments (summary) All-time enrichment counts by status — how many of the account's enrichments are pending, running, finished, or stopped. For the enrichments themselves use [GET /enrichments](#tag/enrich/get/enrichments)`?status=...`.

enrichments_summary

list monitor runs The monitor's run history, newest first. Fetch a specific run's data with [GET /runs/{id}/result](#tag/runs/get/runs/{id}/result). Supports `status`, `page`, and `per_page`.

list_monitor_runs

list monitors List the account's monitors, newest first.

list_monitors

list rows Datasets beta, per account (else 403 `feature_not_enabled`). Rows of a dataset in position order: `input` by column name, `cells` by output column name (`value`, `state`: pending / running / ok / not_found / failed / manual / stale, `reason` + `error` on failed), `credits` and `not_found_reason` per row. `limit` up to 1,000; pass `next_cursor` back as `cursor` for the next page; `updated_since` for changes only.

list_dataset_rows

list runs List the account's runs, newest first. Every async operation shows up here — enrichment runs, dataset builds, extractions, and quick searches. Filter by `type` (comma-separated), `status`, `enrichment_id`, `monitor_id`, and `created_after` / `created_before` (ISO 8601). Paginate with `page` / `per_page`. Pass `ids` (comma-separated, up to 100 run ids) to get those runs' full status objects (same shape as `GET /runs/{id}`) in one call; `not_found` lists ids not on this account. Filters and pagination are ignored.

list_runs

list runs (summary) All-time run counts by status — a snapshot of the account's run queue. For the runs themselves use [GET /runs](#tag/runs/get/runs)`?status=...`.

runs_summary

quick search Run a web search and get structured results back **synchronously** — the response is the run with the results already in `output` (no polling, no webhook). Optionally filter to a date range with `date_start` / `date_end` (format `YYYY-MM-DD`); if only `date_start` is given, `date_end` defaults to today. The result is also stored on the run, so it stays re-fetchable at [GET /runs/{id}/result](#tag/runs/get/runs/{id}/result). For bulk searches — up to **100,000** per request, async with `webhook_url` support — use the legacy [POST /v1/web_search](./openapi.legacy.yaml) endpoint. ## Quick example ```bash curl -X POST https://api.riveterhq.com/v1/quick_search \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "latest OpenAI news"}' ``` ## Credit costs - **0.04 credits** per search. **Example — A simple search:** { "query": "latest OpenAI news" } **Example — A search filtered to a date range:** { "query": "OpenAI GPT-4o mini", "date_start": "2024-07-01", "date_end": "2024-07-31" }

quick_search

read dataset Datasets beta, per account (else 403 `feature_not_enabled`). One dataset by id: `input_columns`, `index_column`, `enrichment_id` + `output_columns` (names; `get_enrichment` has the prompts), `row_count`, `import_in_progress`, newest `runs`. Rows are `list_dataset_rows`.

get_dataset

read enrichment One enrichment by id: `prompt`, `input_columns` (the headers rows must carry), `output` columns (`name`, `prompt`, `output_schema`, a pinned `tool` when the column is one tool call), `tools`, `budget_credits_per_row`, `version`. A legacy enrichment answers `input` (object) and a full `output` column spec instead.

get_enrichment

run extraction Execute a `ready` extraction. Returns a run — poll [GET /runs/{id}](#tag/runs/get/runs/{id}) and fetch the extracted records with [GET /runs/{id}/result](#tag/runs/get/runs/{id}/result) (the records come back as an array of JSON objects matching your schema), or pass a `webhook_url`. `variables` fills any `{{ placeholder }}` values the plan defines (e.g. a search term or location). Each run charges run credits (`credits_charged`). **Workflow:** Starts an async extraction run. Poll `get_run`, then fetch the records with `get_run_result`.

run_extraction

run result The run plus `output`. `output` is `null` until the run reaches a terminal state.. Pass `?wait=N` (max 50) to long-poll: the request holds until the run finishes or the budget elapses, whichever comes first. ## Output shape by run type - **enrichment** — an object mapping column headers to arrays of cell objects: `{ "Company": [{"value": "Apple"}], "CEO": [{"value": "Tim Cook"}] }` - **dataset_build** — an object mapping column headers to arrays of cell objects (same columnar shape as enrichment) - **extraction** — the extracted records as an array of JSON objects (matching your `output_record_json_schema`) - **quick_search** — the search result object `{ "results": [{ "title", "link", "snippet" }, ...], "knowledge_graph"? }`, the same data the synchronous `POST /quick_search` response already carried. (Runs started on the legacy async `/web_search` endpoint share this run type but return the columnar enrichment shape with a `search_results` column.) - **search_agent** — the answer object `{ "result": <string or object> }`; `result` matches the request's `output_schema` when one was given, otherwise it's free text. - **enrichment** on a dataset (`POST /enrich` with `dataset_id`) — `{ "rows": [...] }`: only the rows the fill ran, in position order, each in the `/datasets/{id}/rows` shape (`id`, `position`, `input`, `cells` limited to the columns the fill covered, `credits`). `null` until the run is terminal; `GET /datasets/{id}/rows` is the live view. Above 5,000 rows, or after the rows expire (30 days), `output` is `null` and `output_files` (signed CSV and JSONL links to the whole grid; `pending` until the export lands, valid one hour, see `expires_at`) are the output. - **enrichment** started on `POST /enrich_rows`, or on `POST /enrich` with `input` — the columnar shape while rows are ≤ 5,000, plus the same `output_files`. Above 5,000 rows, or after the rows expire (30 days), `output` is `null` and the files are the output. **Workflow:** `output` is null until the run finishes. Pass `wait` (seconds, max 50) to long-poll instead of sleeping between calls.

get_run_result

run status This returns the **status and progress** of a run for any run created from enrichments, datasets, or extractions. `status` reports the status of the run, and `progress` gives a completion estimate. `?wait=N` (max 50) long-polls: the request holds until the run finishes or the budget elapses. **Workflow:** Pass `wait` (seconds, max 50) to hold the request until the run finishes; repeat until `status` is 'success' or 'stopped'.

get_run

scrape Scrape a webpage and return the text content **synchronously** — the only endpoint here that doesn't return a run to poll. Unchanged from the legacy API (response uses the legacy `request_status` format). ## Quick example ```bash curl -X POST https://api.riveterhq.com/v1/scrape \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com"}' ``` ## Credit costs - **With proxy**: 1/5 credit (0.20 credits) - **Without proxy**: 1/20 credit (0.05 credits) - **From cache**: 1/100 credit (0.01 credits) ## Proxy usage Scraping is not guaranteed to succeed without a proxy. Some websites may block requests or require specific geographic locations. To use a proxy, include `proxy_country_code` with a two-character country code (e.g. 'us', 'gb', 'de'). ## Caching Recently scraped pages are cached to save credits (0.01 credits on a cache hit). Set `skip_cache: true` to always fetch fresh content.

scrape

search agent Ask a question and get an answer. This is meant for quick, relatively scoped one-off questions, like "What is the NAICS code for this company...". For more complex questions, use the `enrich/` endpoint. This uses the same AI + web-tool loop that fills a single agent-mode cell in an enrichment (web search, web scraping, PDF reading, HTTP requests), with no enrichment setup. The run is processed in the background while this request **long-polls up to `wait` seconds (default 50)** — most runs finish in time and return the answer inline in `output.result`. If the agent is still working when the budget elapses, the response comes back with `status: processing` and `output: null`; poll [GET /runs/{id}/result](#tag/runs/get/runs/{id}/result) (it long-polls too) until the run is terminal. Pass `output_schema` (a JSON Schema object) to get `output.result` back as a structured object matching your schema instead of free text. Unanswerable questions return the string `"not found"`. ## Quick example ```bash curl -X POST https://api.riveterhq.com/v1/search_agent \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "Who is the current CEO of Anthropic, and when did they take the role?"}' ``` ## Credit costs - **1 credit** per call (same as one agent-mode enrichment cell), charged when the agent completes. Failed runs are not charged. **Example — A free-text question:** { "prompt": "Who is the current CEO of Anthropic, and when did they take the role?" } **Example — A structured answer via output_schema:** { "prompt": "Find the founding year and headquarters city of Anthropic", "output_schema": { "type": "object", "properties": { "founding_year": { "type": "integer" }, "headquarters_city": { "type": "string" } } } }

search_agent

set input values Datasets beta, per account (else 403 `feature_not_enabled`). Write one row (`row_id`: a `row_...` id or a position) by hand. `input` is `{ "<input column>": value | null }` (an index-column value another row holds is a 422). `cells` is `{ "<output column>": value | null }`: a value becomes a `manual` cell (kept by fills unless `force`); `null` clears it back to `pending`. One write for both. 409 `row_in_use` while a fill is on the row.

update_dataset_row

stop run Stop a run early. Works for every run type. Already-finished runs are left untouched; the response is the run either way. **Workflow:** Stops a running run. The run cannot be resumed after stopping.

stop_run

update dataset Datasets beta, per account (else 403 `feature_not_enabled`). Edit a dataset's structure (no run): `name`; `index_column`; `input_columns` ops (`{ "Name": {} }` add, `{ "rename" }`, `{ "delete": true }`); `output` column ops (new name adds, type inferred unless `output_schema` is given; `{ "prompt", "output_schema" }` changes, cells go `stale`; `{ "rename" }`; `{ "delete": true }`); `budget` (credits per row; moves by 1.5 per output column added or removed unless `budget_locked`) and `budget_locked` (true / false; sent with column changes it wins over that adjustment). Edits a shared enrichment on a private copy. 409 `dataset_in_use` while a fill runs. Then `enrich` with `dataset_id`. `help` with `datasets`, `output_schema`. **Example — Change a prompt, add a typed column, remove one:** { "output": { "CEO": { "prompt": "Full name of the current CEO" }, "Employee count": { "prompt": "Current headcount as an integer", "output_schema": { "type": "integer", "minimum": 0 } }, "HQ city": { "delete": true } } } **Example — Lock the budget and add columns without moving it:** { "budget_locked": true, "output": { "Founded": {}, "Revenue": { "prompt": "Latest annual revenue in USD" } } } **Example — Add an input column and dedupe on it:** { "input_columns": { "Ticker": {} }, "index_column": "Ticker" } **Example — Rename the dataset and a column:** { "name": "Q4 targets", "input_columns": { "Website": { "rename": "Domain" } } }

update_dataset

update enrichment Add, update, rename, or delete output columns, or reorder columns. Send the column changes keyed by column header inside `output` (recommended); a `column_order` array reorders columns. Existing columns can be partially updated; new column names must include a full configuration; set `"delete": true` on a column to remove it. Columns use the same fields as the `output` spec on [POST /enrich](#tag/enrich/post/enrich). **Example — Add a column:** { "output": { "CEO": { "prompt": "Find the company's CEO", "contexts": [ "Company Name" ], "format": "text" } } } **Example — Delete a column:** { "output": { "Old Column": { "delete": true } } }

update_enrichment

update monitor Pause, resume, or repoint a monitor. `enabled: false` pauses, `enabled: true` resumes; `webhook_url` replaces the delivery URL. **Example — Pause:** { "enabled": false } **Example — Resume:** { "enabled": true }

update_monitor

Reference docs for using Riveter well. Call before writing an `output` column spec or when an error mentions a limit. Topics: overview, enrich_modes, column_config, run_when, formats, tools, examples, credits, datasets_vs_enrichment, datasets, pinned_columns, output_schema, limits, webhooks, errors.