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" ], "input": { "Company": [ "Apple", "Google" ] }, "webhook_url": "https://your-server.com/webhook" }

Example — A spec per output column: { "output": { "Employee Count": { "prompt": "Find the number of employees at this company", "output_schema": { "type": "integer" } } }, "input": { "Company": [ "Apple", "Google" ] } }

Example — Fill a dataset's pending, stale, and failed cells: { "dataset_id": "ds_018f6a70-1234-7abc-89ab-0123456789ab" }

Example — Re-run one column on rows 10–12, even if filled: { "dataset_id": "ds_018f6a70-1234-7abc-89ab-0123456789ab", "columns": [ "CEO" ], "positions": [ 10, 11, 12 ], "force": true }

Workflow: Starts an async run. Call get_run_result with the returned run id and wait: 50 until status is 'success'; its output is the 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'.

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?status=....

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.

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

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

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}. The rows land in a dataset named by the run's dataset_id; fill them with 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} and fetch the extracted records with 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} until status is ready, then execute it with 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.

list monitors

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

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

For bulk searches — up to 100,000 per request, async with webhook_url support — use the legacy POST /v1/web_search endpoint.

Quick example

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 (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

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

  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.

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

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.