Retrieve Live Web Data API

What it does

Live Web Data Finder helps you request records from live web pages in plain English, then returns structured results for the fields you asked for. Use it when you need current data from the web without wiring up your own scraping flow.

Send a request string describing the records you want, plus an optional count from 1 to 10. The first call can return a priced response with a confirm_max_atoms value, a max_atoms limit, and a reading summary showing the record count and the columns it will bring back. To start the run, send the same request again with that confirm_max_atoms value. Once the run finishes, you can fetch results with the purchase_id.

The results endpoint returns each matching record with rows, found, and request metadata. Each row includes entity_id, cells, and optional details. Each cell includes the field label, value, and provenance such as source_url and observed_at, so you can trace where the data came from. If a value is missing, the response can also explain why with absence.

Use Live Web Data Finder for workflows like monitoring competitor pricing, collecting current contact or listing data, or pulling live reference fields into a pipeline where freshness matters.

Note: First, submit the request to get the estimated max_atoms, then resend it with the exact confirm_max_atoms value to authorize processing and receive the purchase_id. Use this ID in the second endpoint to check the job status and retrieve the final results once processing is complete.

▣ ENDPOINT 01 / 02

POST

Find live web data

https://api.eu.apyhub.com/specstream/retrieve-live-web-data-api/agent/lists

QUICKSTART

GUIDE

Quickstart

Send the plain-English records request to get a priced read back.

curl -X POST "https://api.eu.apyhub.com/specstream/retrieve-live-web-data-api/agent/lists" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "Find the latest news articles about electric vehicles and return the headline and source",
    "count": 3
  }'

What you'll get back

Returns a JSON object in one of two shapes.

If the run is priced, it returns status, request, reading, max_atoms, confirm_max_atoms, expires_at, and note, where reading is an object with count and columns_asked_for.

If the run has started, it returns purchase_id, status_path, authorized_atoms, reading, status, and charged_atoms; note and find_id may also be present.

{
  "status": "priced",
  "request": "Find the latest news articles about electric vehicles and return the headline and source",
  "reading": {
    "count": 3,
    "columns_asked_for": ["headline", "source"]
  },
  "max_atoms": 1200,
  "confirm_max_atoms": 1200,
  "expires_at": "2026-10-23T12:34:56Z",
  "note": "..."
}

TRY ITLIVE · 2000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Submits a live web data find request and either returns a priced quote or starts the run, depending on whether confirm_max_atoms is included in the request.

Request Body

Parameter	Type	Mandatory	Description
request	String	Yes	The records needed, in plain English, including any conditions and the fields to bring back. Min length 3, max length 2000.
count	Integer	No	How many records to look for, from 1 to 10. Defaults to 10 if omitted.
confirm_max_atoms	Integer	No	The `confirm_max_atoms` value from the priced answer. Sending it starts the run. Must be at least 1. Atoms are ApyHub's unit: 400 atoms per cent of work.

Response

Returns a JSON object with response fields based on the request state: priced when returning pricing information, or running/not_started when the run has started. Refer to the Response Fields table for complete field details

Parameter	Type	Description
status	ENUM	Response state. In the first schema branch it is `priced`. In the second branch it is `running` or `not_started`.
request	String	The request text echoed back in the priced response.
reading	Object	Summary of the requested read. Contains `count` and `columns_asked_for`.
reading.count	Integer	How many records the request asks for.
reading.columns_asked_for	String Array	The fields SpecStream will bring back for each record.
max_atoms	Integer	The most this run can cost, in atoms. Present in the priced response.
confirm_max_atoms	Integer	The maximum atoms value to send back with the same request to start the run. Present in the priced response.
expires_at	String	Expiration timestamp in `date-time` format. Present in the priced response.
note	String	Additional note returned by the service.
purchase_id	String	Purchase identifier returned in the running/not_started response.
status_path	String	Path to the status field used for tracking the run.
authorized_atoms	Integer	The most this run can cost, in atoms.
charged_atoms	Integer	Atoms charged by this call as the run's deposit.
find_id	String	Identifier for the find, present only in the running/not_started response.

▣ ENDPOINT 02 / 02

GET

Get find results

https://api.eu.apyhub.com/specstream/retrieve-live-web-data-api/:purchase_id

QUICKSTART

GUIDE

Quickstart

Check the status of a previously started SpecStream run by its purchase_id.

curl -X GET "https://api.eu.apyhub.com/specstream/retrieve-live-web-data-api/:purchase_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with these top-level fields: purchase_id (string), status (string), reading (object with count and columns_asked_for), requested (integer), and found (integer). The schema also allows rows, request, charged_atoms, and authorized_atoms when present.

{
  "purchase_id": "pur_12345",
  "status": "completed",
  "reading": {
    "count": 10,
    "columns_asked_for": ["title", "price"]
  },
  "requested": 10,
  "found": 10
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Retrieves the current or final results for a previously started find-live-web-data run using the purchase_id path parameter. The response includes the run status plus any read records and summary counts available for that purchase.

Path Parameter(s)

Attribute	Type	Mandatory	Description
purchase_id	String	Yes	The `purchase_id` returned when the run started.

Response

Returns a JSON object with response fields showing the run status and results. Refer to the Response Fields table for complete field details.

Parameter	Type	Description
purchase_id	String	The purchase identifier for this run.
status	ENUM	Run status. Allowed values: `running` (still searching), `completed` (finished successfully), `partial` (timeout - partial results), `failed` (error occurred), `canceled` (user canceled), `expired` (timed out), `not_started` (queued).
reading	Object	Summary of what the run is asking for. Includes required `count` (`integer`) and `columns_asked_for` (`string array`).
requested	Integer	Number of records requested.
found	Integer	Records found so far.
rows	Object Array	Every record that met the request. Present when the run has ended. Each row object includes `entity_id` (`string`) and `cells` (`array`) as required fields, plus optional `details` (`array`), `ordinal` (`integer`), and `billable` (`boolean`). Each cell includes `column_id`, `label`, `value`, `display`, `absence` (if value is missing), and `provenance` (with `source_url` and `observed_at`).
request	String	The request string.
charged_atoms	Integer	Atoms charged for the run in all, including the start. Present when the run has ended.
authorized_atoms	Integer	Authorized atoms for the run.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Similar APIs

Closest matches in the catalog based on this service.

CALLWeb Scraping APISharpAPI CALLWeb Search & Analysis APISkycraft CALLExtract Structured Data APISumalya APIs CALLExtract Metadata From URL APISumalya APIs

From the blog

Reads that touch this API.

Web Data Extraction: Use Cases and ApproachesJul 9, 2026 Why Manual Scraping SERP Data Is Dead: The Rise of Reliable SERP APIs in 2026Aug 5, 2026 A Developer’s Guide to Searching and Extracting Company Data ProgrammaticallyAug 7, 2026 Web Scraping in 2026: What Changed, What's Legal, and What to Use InsteadSep 4, 2026