add_dataset_rows
ChatGPTadd rows Datasets beta, per account (else 403 feature_not_enabled). 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.
build_configured_dataset
ChatGPTbuild 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 dataset-build run; poll [GET /runs/{id}](#tag/runs/get/runs/{id}). Example — Fill in template parameters: { "parameters": { "practice_type": "dentists", "state": "ohio" } } Workflow: Starts an async run of a configured dataset. Poll get_run, then fetch with get_run_result.
build_dataset
ChatGPTbuild dataset Build a dataset: rows Riveter finds, or rows you send. The body picks the mode. List build (on every account): prompt and / or identifiers + qualifiers, max_items (row cap); attributes (≤ 20) are saved for a later enrichment, not filled (auto_run_enrichment: true fills them, a second paid run). Returns a run plus dataset_id; then enrich with that dataset_id and a column config. help with datasets_vs_enrichment. Dataset (beta per account, else 403 feature_not_enabled): rows (≤ 100 objects keyed by input column name, free) or prompt + count (generated, paid); output columns from attributes or enrichment_id; auto_fill: true fills generated rows when they land. Returns the dataset (id, ds_...) and run (the generation run, or null); then enrich with dataset_id alone. help with datasets. estimate_cost: true prices either mode first. Example — List build — prompt with identifiers and qualifiers: { "prompt": "Top 50 US SaaS companies with their websites", "identifiers": [ "Company name", "Website" ], "qualifiers": [ "US-based", "SaaS" ], "max_items": 50 } Example — List build — build and auto-enrich in one step, refused above 200 credits: { "prompt": "Top 50 US SaaS companies", "attributes": [ "CEO", "Revenue" ], "max_items": 50, "auto_run_enrichment": true, "max_credits": 200 } Example — Dataset (beta) — rows you have, two columns to fill: { "name": "Targets", "rows": [ { "Company": "Apple", "Website": "apple.com" }, { "Company": "Shopify" } ], "attributes": [ "CEO", "HQ city" ] } Example — Dataset (beta) — generate 50 rows and fill them when they land: { "prompt": "Specialty coffee roasters in San Francisco", "count": 50, "input_columns": [ "Roaster", "Website" ], "attributes": [ "Founded year" ], "auto_fill": true } Workflow: Starts an async dataset build run. Poll get_run until status is 'success', then fetch the rows with get_run_result. Pass auto_run_enrichment: true to enrich the rows in the same flow.
build_dataset_for_enrichment
ChatGPTenrichment → 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_rows
ChatGPTgenerate 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 }
create_enrichment
ChatGPTcreate enrichment Create an enrichment (no run) from a completed dataset build: the dataset's rows become the enrichment's input rows, and its attributes become output columns. Configure further in the UI or via [PATCH /enrichments/{id}](#tag/enrich/patch/enrichments/{id}), then run with [POST /enrich](#tag/enrich/post/enrich).
create_monitor
ChatGPTcreate monitor Create a monitor: a schedule that re-runs an enrichment daily, weekly, or monthly over fixed input rows and can POST results (or only changes) to a webhook. Creation is free; every scheduled run charges the enrichment price for input. estimate_cost: true prices one run. Without input, runs fail with no_monitor_input. Example — Daily monitor with change alerts: { "enrichment_id": "enr_018f5b60-1234-7abc-89ab-0123456789ab", "cadence": "daily", "hour": 9, "minute": 0, "timezone": "UTC", "alert_rule": "only_on_change", "webhook_url": "https://your-server.com/webhook", "input": { "Company Name": [ "Acme Corp", "Tech Solutions Inc" ] } } 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.
delete_dataset
ChatGPTdelete dataset Datasets beta, per account (else 403 feature_not_enabled). Delete a dataset by id (rows and cells with it; its enrichment stays). 409 dataset_in_use while a run is on it.
delete_dataset_rows
ChatGPTdelete 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_enrichment
ChatGPTdelete enrichment Datasets beta, per account (else 403 feature_not_enabled). Delete an enrichment by id. Runs in flight finish; a dataset bound to it keeps its columns. Legacy enrichments cannot be deleted here.
enrich
ChatGPTenrich 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.
enrichments_summary
ChatGPTlist 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=....
export_dataset
ChatGPTexport 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).
extend_dataset
ChatGPTextend 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.
get_account
ChatGPTaccount 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).
get_dataset
ChatGPTread 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_enrichment
ChatGPTread enrichment One enrichment by id: prompt, input_columns (the headers rows must carry), output columns (name, prompt, output_schema), tools, budget_credits_per_row, version. A legacy enrichment answers input (object) and a full output column spec instead.
get_monitor
ChatGPTget monitor The monitor's schedule, webhook, and next run time.
get_run
ChatGPTrun 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_result
ChatGPTrun 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.
help
ChatGPTReference 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, output_schema, limits, webhooks, errors.
import_dataset_rows
ChatGPTimport 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.
list_dataset_rows
ChatGPTlist 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_datasets
ChatGPTlist 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_enrichments
ChatGPTlist 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_monitor_runs
ChatGPTlist 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_monitors
ChatGPTlist monitors List the account's monitors, newest first.
list_runs
ChatGPTlist 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.
promote_dataset_column
ChatGPTconvert output column to input Datasets beta, per account (else 403 feature_not_enabled). 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.
quick_search
ChatGPTquick 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" }
runs_summary
ChatGPTlist 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=....
scrape
ChatGPTscrape 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.
search_agent
ChatGPTsearch 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" } } } }
stop_run
ChatGPTstop 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.
update_dataset
ChatGPTupdate 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 }). 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 — 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_row
ChatGPTset 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_enrichment
ChatGPTupdate 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_monitor
ChatGPTupdate 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 }
