riveter-sdk

Official Python SDK for the Riveter API — enrich data, build datasets, scrape pages, and run web searches.

Requires Python 3.9+. The import name is riveter.

Install

pip install riveter-sdk

Quickstart

from riveter import Riveter

# Reads RIVETER_API_KEY from the environment when api_key is not passed.
# Get a key at https://app.riveterhq.com/settings/api
riveter = Riveter(api_key="YOUR_API_KEY")

run = riveter.enrich(
    prompt="Research each company",
    attributes=["CEO", "Employee Count"],
    input={"Company": ["Apple", "Google"]},
)

result = riveter.runs.wait_for_result(run.id)
print(result.output)

The run lifecycle

Every async kickoff (enrich, datasets.build, extractions.run, ...) returns a run.

riveter.runs.get(run.id)                          # status + progress
riveter.runs.result(run.id, wait=50)              # output (long-polls up to 50s)
riveter.runs.wait_for_result(run.id, timeout=600) # poll until finished
riveter.runs.stop(run.id)                         # stop early

List runs with automatic pagination:

for run in riveter.runs.list(status="success").auto_paging_iter():
    print(run.id)

Surface

• riveter.enrich(...), riveter.quick_search(...), riveter.scrape(...), riveter.account()
• riveter.runs — get, result, stop, list, summary, wait_for_result
• riveter.enrichments — list, create, get, update, build_dataset
• riveter.datasets — build, extend
• riveter.configured_datasets — build
• riveter.extractions — create, get, run
• riveter.monitors — create, list, get, update, runs

Responses are lightweight dataclasses; fields the SDK does not know yet stay reachable via .raw.

Errors and retries

API failures raise riveter.APIError with status, type (not_found, insufficient_credits, ...), message, and optional details. Network failures raise APIConnectionError / APITimeoutError. 429s are retried automatically using the X-RateLimit-Reset header; 5xx and network failures are retried for GETs. Configure with max_retries and timeout.

Options

Riveter(
    api_key="...",                            # default: env RIVETER_API_KEY
    base_url="https://api.riveterhq.com/v1",  # default: env RIVETER_BASE_URL, then this
    timeout=60.0,                             # keep above 50 for `wait` long-polls
    max_retries=2,
)