Riveter

enrich Add AI-researched columns to rows. Rows come from exactly one of `dataset_id` (`ds_...`, preferred) or `input` (inline, columnar: `{ "Header": ["row1", "row2"] }`, all arrays equal length; a one-off, nothing kept). Preferred: put the rows in a dataset first (`build_dataset` with `rows` + `attributes` or `enrichment_id`, free; it keeps the rows and filled cells), then `enrich` with its `dataset_id`: fills its cells with its enrichment; no column config needed. Default scope: every `pending`, `stale`, or `failed` cell; `columns`, `rows`, `positions` narrow it; `force: true` re-runs filled cells. `prompt` + `attributes` fills the named columns, adding the missing ones first; `output` is refused (`update_dataset` sets a column's prompt / schema / tool). `help` with `datasets`. With `input`, column config is exactly one of, most consistent first: 1. `enrichment_id` — a saved enrichment (`enr_...`, `list_enrichments`): fixed, tested config; up to 10,000 rows; input headers must match its input columns (`get_enrichment`). 2. `prompt` + `attributes` — the task and up to 20 column names; no setup; up to 1,000 rows. 3. `output` — per column `prompt`, optional `output_schema`, optional pinned `tool`; up to 1,000 rows. `help` with `column_config` or `examples` first. Returns a run. Poll `get_run_result` with `wait: 50` (or pass `webhook_url`); a dataset fill's result is `{ "rows": [...] }`, only the rows it ran. `estimate_cost: true` prices it without running. A `legacy` key in the response means the call took a legacy mode (a legacy enrichment's id, legacy-pipeline column fields); follow `legacy.successor`. **Example — Run a saved enrichment:** { "enrichment_id": "enr_018f5b60-1234-7abc-89ab-0123456789ab", "input": { "Company Name": [ "Acme Corp", "Tech Solutions Inc" ] } } **Example — Prompt + attributes (a task and column names):** { "prompt": "Research each company", "attributes": [ "CEO", "Employee Count", "Industry"

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'.

run result The run plus `output`, `null` until the run finishes. 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** — the 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`). `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.

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.

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`, `dataset_id`, `monitor_id`, and `created_after` / `created_before` (ISO 8601). Paginate with `page` / `per_page`. `enrichment_id` naming a legacy enrichment still filters and the response carries `legacy`. 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 (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=...`.

Takes no parameters.

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` key means the id is a legacy enrichment's; its `successor` names the dataset copy.

update enrichment Edit an enrichment: `name`, `prompt`, `input_columns`, `budget` (credits per row; moves by 1.5 per output column added or removed unless `budget_locked`), `only_tools` / `additional_tools`, and `output` columns by name: a new name adds a column (type inferred unless `output_schema` is given), `{ "prompt", "output_schema" }` changes one, `{ "tool": "<list_tools name>" }` pins a tool to it — one call per row is the cell, the agent choosing the arguments (`null` unpins; `help` with `pinned_columns`), `{ "rename" }` renames, `{ "delete": true }` removes. Changed columns make dataset cells `stale` (re-run by the next `enrich`). 409 `enrichment_in_use` while a fill runs. Prefer `update_dataset` to change one dataset's columns. `help` with `output_schema`. **Example — Change one column's prompt, add a typed one:** { "output": { "CEO": { "prompt": "Full name of the current CEO" }, "Employee count": { "prompt": "Current headcount as an integer", "output_schema": { "type": "integer", "minimum": 0 } } } } **Example — Rename a column, delete another:** { "output": { "HQ": { "rename": "HQ city" }, "Old Column": { "delete": true } } } **Example — New prompt and budget:** { "prompt": "Research each company's go-to-market motion", "budget": 8 }

delete enrichment Delete an enrichment by id. Runs in flight finish; a dataset bound to it keeps its columns. A legacy enrichment's id is refused (422 with `legacy`); those are deleted in the app.

list enrichments The account's enrichments, newest first: id, name, input / output column names. A legacy enrichment's item also has `status`, `app_url`, and `dataset_id` (its dataset copy: `enrich` that instead). Paginate with `page` / `per_page` (max 50); filter by `status` (legacy only), `name`. `get_enrichment` has the columns' config.

create enrichment Create an enrichment (no run, free) and the empty dataset it fills, bound to it and in the app at `app_url`. A recipe: `prompt` (the task), `output` columns (names, or `{ name, prompt, output_schema, tool }` — `tool: "<list_tools name>"` pins a tool: one call per row, arguments chosen by the agent, result is the cell; `help` with `output_schema` / `pinned_columns`), optional `input_columns`, `budget` (credits per row, default 1.5 per output column; follows column adds / removes unless `budget_locked`), `only_tools` / `additional_tools` (`list_tools`). Prefer `prompt` alone: the output columns (one typed column per fact asked for), name, and input columns are written from it; the response shows them. Then `add_dataset_rows` to the `dataset_id` and `enrich` with it (preferred), or `enrich` with `enrichment_id` + `input` for a one-off. `dataset_id` alone answers a dataset's own enrichment as `{ id, name, app_url, dataset_id }` (422 without output columns; add them with `update_dataset`). **Example — Save a recipe — three columns, one typed:** { "name": "Company basics", "prompt": "Research each company from its name and website.", "input_columns": [ "Company", "Website" ], "output": [ "CEO", { "name": "Employee count", "prompt": "Current headcount as an integer", "output_schema": { "type": "integer", "minimum": 0 } }, { "name": "Summary", "prompt": "Two sentences on what the company sells and to whom" } ], "budget": 4 } **Example — The recipe written from the prompt — columns, name, and input columns:** { "prompt": "Research each company from its name and website: the CEO, employee count, latest funding round date and amount, and whether it is hiring." } **Example — A dataset's own enrichment:** { "dataset_id": "ds_018f6a70-1234-7abc-89ab-0123456789ab" }

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

Takes no parameters.

build dataset Build a dataset: rows you send or rows Riveter finds. `rows` (≤ 100 objects keyed by input column name, free) or `prompt` + `count` (generated, paid); output columns from `attributes` or `enrichment_id`, or, with `prompt` + `count` alone, written from the prompt (one typed column per fact it asks for) along with the identity columns; `auto_fill: true` fills generated rows when they land; `budget` caps a generation's spend (default 50 + 1.5 per row; deposit of expected charged now, rest as it runs). Returns the dataset (`id`, `ds_...`) and `run` (the generation run, or null); then `enrich` with `dataset_id` alone. `estimate_cost: true` prices it first. `help` with `datasets`. **Example — Rows you have, two columns to fill:** { "name": "Targets", "rows": [ { "Company": "Apple", "Website": "apple.com" }, { "Company": "Shopify" } ], "attributes": [ "CEO", "HQ city" ] } **Example — Generate 50 rows on a 100-credit budget, filled when they land, refused above 200 credits:** { "prompt": "Specialty coffee roasters in San Francisco", "count": 50, "input_columns": [ "Roaster", "Website" ], "attributes": [ "Founded year" ], "auto_fill": true, "budget": 100, "max_credits": 200 } **Example — The whole dataset from the prompt — identity columns and typed output columns:** { "prompt": "Top 50 US fintech startups with their CEO, total funding, and founding year", "count": 50, "auto_fill": true } **Workflow:** The response is the dataset and, with `prompt` + `count`, a generation `run` — poll it with `get_run`, then read the rows with `list_dataset_rows` (`auto_fill: true` researches them as they land).

read dataset 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`.

update dataset 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`; `{ "tool": "<list_tools name>" }` pins a tool: one call per row, arguments chosen by the agent, result is the cell (`null` unpins); `{ "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`, `pinned_columns`, `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 — A column pinned to the LinkedIn profile lookup; the agent finds the URL to call it on:** { "output": { "Profile": { "prompt": "The LinkedIn profile of the row's person; find the canonical linkedin.com/in/<slug> URL first", "tool": "linkedin_person_profile" } } } **Example — Rename the dataset, add an input column and dedupe on it, rename another:** { "name": "Q4 targets", "input_columns": { "Ticker": {}, "Website": { "rename": "Domain" } }, "index_column": "Ticker" }

delete dataset Delete a dataset by id (rows and cells with it; its enrichment stays). 409 `dataset_in_use` while a run is on it.

list rows 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. To read a whole dataset: `columns` names the columns, `compact: true` makes rows `{ position, input, cells: { "<column>": value } }`; 1,000 rows of one column is one call. For counts of a column's values or states, `get_dataset_summary`.

add rows Append up to 100 rows (objects keyed by input column name; free). Duplicates on the index column are skipped (`skipped_duplicates`). Returns the inserted rows. Then `enrich` with `dataset_id`. More rows: `import_dataset_rows`.

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

import rows (CSV) 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.

generate more rows 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 }

set input values 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` for `input` while a fill is on the row; `cells` land meanwhile and stand over the run's answer.

convert output column to input Make a filled output column an input column of the same name (`column`); every row's value moves with it, so later columns and dedupe can key on it. Not undoable; 409 `dataset_in_use` while a fill runs.

export dataset (CSV, Excel, or JSON Lines) 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); for a whole dataset, `list_dataset_rows` with `columns` + `compact`; for counts, `get_dataset_summary`.

summarize columns Counts over every row of a dataset, no rows read: per column, `states` (an output column's cells: pending / stale / failed / not_found / ok / manual), `filled`, `distinct_values`, and `values` (the `top_values` most common as `{ value, count }`, default 20, max 100; strings cut at 200 characters). The call for "how many of each", "how many are not found", "what does this column hold", and what a fill filled. `columns` picks the columns; absent, all.

build configured list Run a **configured list build** — a reusable, pre-configured list template (id `cds_...`) set up for your account ("Configured list builds" in the app). The spec, prompt template, row cap, and per-run credit cost are all defined on the template; you only supply `parameters` to fill in its `{{ placeholder }}` values. Returns the list-build run; poll [GET /runs/{id}](#tag/runs/get/runs/{id}). The rows land in a dataset named by the run's `dataset_id`; fill them with [POST /enrich](#tag/enrich/post/enrich). **Example — Fill in template parameters:** { "parameters": { "practice_type": "dentists", "state": "ohio" } } **Workflow:** Starts an async run of a configured list build. Poll `get_run`; the rows land in the dataset the run's `dataset_id` names (`list_dataset_rows`), then `enrich` with it.

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`.

create extraction Create an **extraction** — a reusable recipe for scraping structured records from a website — and start its agent discovery. Discovery explores the site, builds the scrape/extract plan, and validates it against your schema. Poll [GET /extractions/{id}](#tag/extractions/get/extractions/{id}) until `status` is `ready`, then execute it with [POST /extractions/{id}/runs](#tag/extractions/post/extractions/{id}/runs). The extraction (`ext_...`) and its runs (`run_...`) are different resources. Creating an extraction charges discovery credits (returned as `credits_charged`). To see the price first, send `estimate_cost: true`. **Example — Create an extraction:** { "starting_url": "https://example.com/products", "goal_description": "Extract every product with its name and price", "output_record_json_schema": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "string" } } }, "required_keys": [ "name" ] } **Workflow:** Discovery is async but returns no run — poll `get_extraction` until `status` is 'ready', then execute with `run_extraction`.

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).

list monitors List the account's monitors, newest first. An item whose monitor runs a legacy enrichment carries `legacy: true`.

Takes no parameters.

create monitor Create a **monitor**: a schedule that fills a dataset's output columns again daily, weekly, or monthly, compares each cell with the previous run, and can POST results (or only changes) to a webhook. Pass `dataset_id` and optionally `columns` (output column names; every one when omitted); the rows are the dataset's, no `input`. Creation is free; every run charges the fill price. `estimate_cost: true` prices one run. `help` → `monitors`. **Example — Daily monitor on a dataset, webhook only on changes:** { "dataset_id": "ds_018f5b60-1234-7abc-89ab-0123456789ab", "columns": [ "Headcount", "Latest funding round" ], "cadence": "daily", "hour": 9, "minute": 0, "timezone": "UTC", "alert_rule": "on_diff", "output_format": "include_diffs", "webhook_url": "https://your-server.com/webhook" } **Example — Weekly monitor, every output column, results every run:** { "dataset_id": "ds_018f5b60-1234-7abc-89ab-0123456789ab", "cadence": "weekly", "day_of_week": 1, "hour": 7, "minute": 30, "timezone": "America/New_York", "webhook_url": "https://your-server.com/webhook" } **Workflow:** Creates a scheduled monitor. Check it with `get_monitor`, pause it with `update_monitor` (enabled: false), and list its runs with `list_monitor_runs`.

get monitor The monitor's schedule, webhook, next run time, and the dataset and `columns` it fills. A monitor on a legacy enrichment answers with `legacy`.

update monitor Pause, resume, or repoint a monitor. `enabled: false` pauses, `enabled: true` resumes; `webhook_url` replaces the delivery URL; `columns` changes the output columns each run fills — `null` for every column (refused on a monitor on a legacy enrichment, whose response carries `legacy`). **Example — Pause:** { "enabled": false } **Example — Resume:** { "enabled": true } **Example — Fill two columns only:** { "columns": [ "Headcount", "Latest funding round" ] }

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`. A monitor on a legacy enrichment answers with `legacy`.

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" }

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" } } } }

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**: 0.30 credits - **Without proxy**: 0.10 credits - **From cache**: 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.

list agent tools The tools an enrichment may list in `only_tools` / `additional_tools` or pin to an output column (`tool`): name, what it does, what a call takes (`inputs`, each with `required`; `input_groups` when any one complete set is enough) and gives back (`returns`) — the values a pinned column's row must carry or the agent must find —, credits per call (`price_note` when the price settles after the call — the LinkedIn email / phone tools only on a contact, `text_search_pdf` per page, `pdf` / `image` by tokens spent reading it), whether it is on by default, whether it needs opt-in and is enabled on this account, and for a tool that uses the account's own provider key (Apollo, Hunter, Findymail, curl, USPTO) whether one is linked (`api_key_linked`; refused until it is). Also the `budget` (credits per row) range and per-column default.

Takes no parameters.

account Information about the account associated with the API key: plan, credit balance, and the key's metadata. Unchanged from the legacy API (response uses the legacy `request_status` format).

Takes no parameters.

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, monitors, errors.