Search and Fetch With Web Data - Floppydata Client API

Web Data supports two jobs: search for relevant public pages, or fetch rendered HTML from a URL you already know.

Job	Endpoint	Use it when
Search the web	`POST /v2/web-data/search`	You need to discover relevant pages from a query.
Fetch a page	`POST /v2/web-data/fetch`	You already have a URL and need its rendered HTML.

Search the Web

Request

curl --request POST \
  --url "$FLOPPY_BASE_URL/v2/web-data/search" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: $FLOPPY_API_KEY" \
  --data '{
    "query": "Playwright browser automation",
    "numResults": 5
  }'

Response

{
  "requestId": "b111bdad-09aa-41df-a216-5b22d85db45c",
  "query": "Playwright browser automation",
  "results": [
    {
      "id": "8ec7797f-d0b8-474d-a128-d96e88155253",
      "title": "Browser automation guide",
      "url": "https://example.com/browser-automation",
      "snippet": "A practical guide to browser automation."
    }
  ]
}

query is required and accepts 1 to 200 characters after surrounding whitespace is removed. numResults accepts an integer from 1 to 25 and defaults to 10. The API can return fewer results than requested or an empty results array when no pages match. Search returns lightweight organic results in ranking order. AI overviews, related questions, and location controls are not included. Results come from Google Search. The search engine is fixed and cannot be changed per request.

Fetch a Page

Request

curl --request POST \
  --url "$FLOPPY_BASE_URL/v2/web-data/fetch" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: $FLOPPY_API_KEY" \
  --data '{
    "url": "https://example.com",
    "countryCode": "US",
    "city": "New York",
    "difficulty": "low",
    "cacheMaxAgeDays": 0
  }'

Response

{
  "html": "<!doctype html><html>...</html>",
  "sourceUrl": "https://example.com",
  "fetchedAt": "2026-06-10T12:00:00.000Z"
}

Useful Fields

Field	Use
`url`	Target page to fetch. Required.
`countryCode`	Optional two-letter exit country code.
`city`	Optional city for the request exit location.
`difficulty`	Optional pool selector: `low` or `medium`.
`cacheMaxAgeDays`	Optional maximum cached content age in days.

Balance and Usage

Check Web Data request balance:

curl --request GET \
  --url "$FLOPPY_BASE_URL/v2/web-data/balance" \
  --header "X-Api-Key: $FLOPPY_API_KEY"

Check Web Data usage:

curl --request GET \
  --url "$FLOPPY_BASE_URL/v2/web-data/usage?from=2026-03-01&to=2026-03-12" \
  --header "X-Api-Key: $FLOPPY_API_KEY"

Usage responses include yesterday, last7Days, last30Days, lastUpdatedAt, and requestedRange when a date range is supplied.

Usage Tips

Situation	Tip
You need to discover pages	Search first, then pass a result `url` to the fetch endpoint when you need rendered HTML.
You only need a page fetched	Send only `url` first, then add location options if the target behaves differently by region.
You need a country exit	Use `countryCode` as a two-letter code such as `US`.
You need a city exit	Add `city` with `countryCode`; city availability depends on backend location data.
The target is harder to access	Try `difficulty: "medium"` after a simple request fails or returns unusable content.
You want fresh content	Set `cacheMaxAgeDays` to `0`. Higher values allow cached content when available.
Search returns `502`	Retry later. Upstream search failures do not consume request balance.
Fetch fails	A scrape failure returns a structured error. Treat `"Failed to scrape the URL"` as a target/upstream fetch failure, not an API-key failure.

Each successful search or fetch consumes one Web Data request. Validation, authentication, and upstream failures do not consume request balance. Check GET /v2/web-data/balance before running a batch.

Run Web Data search

Search from the API Reference and inspect the ordered organic results.

Run Web Data fetch

Fetch a URL and inspect the full request and response schema.

​Search the Web

​Request

​Response

​Fetch a Page

​Request

​Response

​Useful Fields

​Balance and Usage

​Usage Tips

Run Web Data search

Run Web Data fetch

Search the Web

Request

Response

Fetch a Page

Request

Response

Useful Fields

Balance and Usage

Usage Tips