Extractions

create extraction

Changed on Oct 30, 2026

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.

post/extractions

Request

Base URL
https://api.riveterhq.com/v1
Auth
HTTP bearer
TypeScript
https://skmtc.dev/riveterhq/apis/riveter-api/docs/extractions/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

starting_urlstring uri required

Where the agent starts exploring

goal_descriptionstring required

What records to extract, in plain language

output_record_json_schemaobject required

JSON schema of one output record

namestring

Optional display name

required_keysstring[]

Record keys that must be non-empty for a record to count

estimate_costboolean

Validate and price the request without running or charging anything; the 200 response is the credit estimate (EstimateCostResult).

max_creditsnumber

Credit ceiling. Refused with 422 credit_cap_exceeded (nothing charged) when the estimate's maximum exceeds it.

Response

estimate_cost only — the discovery price (type extraction_discovery); nothing was created or charged

estimate_costtrue required

What would have been charged for (monitor = one scheduled run of the monitor)

Example response

{
  "estimate_cost": true,
  "type": "enrichment",
  "credit_detail": {
    "estimate": {
      "minimum": 0,
      "maximum": 1920,
      "charged_upfront": false
    },
    "credits_used": 0,
    "credits_remaining": 5000,
    "sufficient_credits": true
  }
}

Changes

Oct 30, 2026dcb4d45ade1a Revision changes
- info
  added the optional property ////// to the response with the status
- info
  added the optional property ////// to the response with the status
- info
  added the optional property ////// to the response with the status
- info
  added the optional property ////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
Oct 13, 2026029668894d33 Revision changes
- info
  added the optional property ////// to the response with the status
- info
  added the optional property ////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status

Operation history (5 revisions)