---
title: Retrieve Live Web Data API
slug: retrieve-live-web-data-api
url: https://apyhub.com/specstream/service/retrieve-live-web-data-api
provider: SpecStream
tags: [web-scraping, live-data, data-extraction, web-research, company-data, sec-filings, b2b-data, lead-data, ai-agents]
auth: api_key
version: 1.0.0
service_type: job
endpoints: 2
atoms: 1-2000
mcp: true
---

# Retrieve Live Web Data API

Describe the records you need in plain English and get structured data read from the live web: companies, local businesses, SEC filings, tenders, grants and jobs, every value with its source page.

## Endpoints

| Method | URL | Description | Atoms |
| --- | --- | --- | --- |
| POST | `https://api.eu.apyhub.com/specstream/retrieve-live-web-data-api/agent/lists` | What it does Submits a live web data find request and either returns a priced quote or starts the r… | 2000 |
| GET | `https://api.eu.apyhub.com/specstream/retrieve-live-web-data-api/:purchase_id` | What it does Retrieves the current or final results for a previously started find-live-web-data run… | 1 |

## Endpoint reference

### Find live web data

`POST https://api.eu.apyhub.com/specstream/retrieve-live-web-data-api/agent/lists` · 2000 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `count` | body | integer | no | How many records to look for, from 1 to 10. Leave it out for 10. |
| `request` | body | string | yes | The records you need, in plain English, with any conditions and the fields to bring back. |
| `confirm_max_atoms` | body | integer | no | The confirm_max_atoms value from the priced response to start the run. |

#### Quickstart

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

```bash
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.

```json
{
  "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": "..."
}
```

### Get find results

`GET https://api.eu.apyhub.com/specstream/retrieve-live-web-data-api/:purchase_id` · 1 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `purchase_id` | path | string | yes | The purchase_id returned when the run started. |

#### Quickstart

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

```bash
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.

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

## About

## 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.

## Usage

Base URL: `https://api.eu.apyhub.com` (default region — see
`GET https://apyhub.com/api/public/regions` for the rest).

Authenticate with an ApyHub API key in the `apy-token` header.
Full docs and a live playground: https://apyhub.com/specstream/service/retrieve-live-web-data-api