> ## Documentation Index
> Fetch the complete documentation index at: https://floppydata.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Search and Fetch With Web Data
> Discover public pages with search, then fetch rendered HTML when needed.
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
```bash theme={null}
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
```json theme={null}
{
"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
```bash theme={null}
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
```json theme={null}
{
"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:
```bash theme={null}
curl --request GET \
--url "$FLOPPY_BASE_URL/v2/web-data/balance" \
--header "X-Api-Key: $FLOPPY_API_KEY"
```
Check Web Data usage:
```bash theme={null}
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.
Search from the API Reference and inspect the ordered organic results.
Fetch a URL and inspect the full request and response schema.