Skip to main content
An extract answers with an id. GET /v1/extract/{id} returns what it found, for 24 hours, and costs nothing.

Read a result

Get an API key in the Quickstart. Use the id that Extract returned.

Read the response

This is the real result of the request on Extract.

Show sources

Send "showSources": true with the extract to get sources: for each field, the pages whose text states the value. Use it to link a value back to its page. This real result came from a call that also sent showSources.
A field that is not in data is not in sources. The full request is on Schema.

Set a timeout

timeout is how long to keep reading the pages, in milliseconds, from 1,000 to 300,000. The default is 30,000 ms. A page that is not read by then is skipped, named in warning, and costs nothing. The call fails only when no page can be read.
After the pages are read, the answer takes up to 45 more seconds. Set your client timeout above timeout plus 45 seconds. warning reads like Read 1 of 2 pages. Skipped <url>: <reason>, and like 1 of 1 pages were longer than 50000 characters and were cut there. when a page is long. With several pages, each page gets a smaller share, and all together are read up to 150,000 characters.

Get a webhook

Send webhook with a public address, or with an object, to be told when the extract ends instead of asking.
Stophy sends one JSON POST when the extract ends. It has the id, the event (completed or failed), the status, the data, confidence, urls, warning, sources, costUsd and your metadata. Each call is signed: Stophy-Signature holds t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<body> with your webhook secret. A call that gets no 2xx answer is sent again, up to 3 times. See Webhooks.

Options

Limits and errors

  • A result is kept for 24 hours. With zeroDataRetention it is kept for 1 hour. After that, GET returns 404 notFound with No extract with that id. Results are kept for 24 hours.
  • A call that cannot read any page fails with the error of the page, such as sourceTimeout or siteNotRead. A failed call costs nothing, and a failed extract can be read back with status of failed.
  • Without an API key, GET /v1/extract/{id} returns 401 apiKeyRequired. You can read only your own results.
  • More than 25 urls returns 400 invalidRequest. urls with no public page in them returns 400 invalidRequest with None of these is a public website URL.