> ## 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
> Searches the public web and returns lightweight organic results in ranking order. One successful search consumes one Web Data request. Use this to discover relevant pages; use fetchWebData when you already have a URL and need its HTML. AI overviews, related questions, and location controls are not included.
This playground sends real production requests. Each successful search consumes one Web Data request.
Results come from Google Search. The search engine is fixed; this endpoint does not accept an engine selector.
## OpenAPI
````yaml api-reference/openapi.json POST /v2/web-data/search
openapi: 3.1.0
info:
title: Floppydata Client API
description: >-
Client API v2 for Web Data, proxy products, proxy tools, and account
rollups. You can manage your API keys in [API
keys](https://app.floppydata.com/api-keys).
version: 2.0.0
servers:
- url: https://api.floppydata.net
description: Production
security:
- apiKeyHeader: []
tags:
- name: Web Data
description: Fetch pages and inspect Web Data balance and usage.
- name: Proxy
description: Proxy tools shared across proxy products.
- name: Rotating Proxy
description: Rotating proxy subusers, connections, locations, balance, and usage.
- name: Static Proxy
description: Static proxy inventory for the authenticated account.
- name: Account
description: Account-level balance and usage rollups across available products.
- name: Cloud Browser
description: |-
Session-first cloud browsers with persistent settings under the hood.
Create a session, connect using the returned WebSocket URL, then navigate with Playwright or Puppeteer. Reuse settings.id to restore the same identity and browser state.
paths:
/v2/web-data/search:
post:
tags:
- Web Data
summary: Search the web with Web Data
description: >-
Searches the public web and returns lightweight organic results in
ranking order. One successful search consumes one Web Data request. Use
this to discover relevant pages; use fetchWebData when you already have
a URL and need its HTML. AI overviews, related questions, and location
controls are not included.
operationId: searchWebData
requestBody:
content:
application/json:
schema:
type: object
properties:
query:
type: string
minLength: 1
maxLength: 200
description: Search query. Whitespace is trimmed before searching.
example: browser automation
numResults:
default: 10
description: Maximum number of organic results to return.
example: 10
type: integer
minimum: 1
maximum: 25
required:
- query
additionalProperties: false
responses:
'200':
description: Normalized organic search results.
content:
application/json:
schema:
type: object
properties:
requestId:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: Unique identifier for this search request.
query:
type: string
minLength: 1
description: Normalized search query.
results:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: Unique identifier for this result.
title:
type: string
minLength: 1
description: Page title.
url:
type: string
format: uri
description: Page URL.
snippet:
description: Search result excerpt when available.
type: string
minLength: 1
required:
- id
- title
- url
additionalProperties: false
description: Organic results in provider ranking order.
required:
- requestId
- query
- results
additionalProperties: false
example:
requestId: b111bdad-09aa-41df-a216-5b22d85db45c
query: 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.
'400':
description: The request body or query parameters are invalid.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: invalid_request
message: Invalid request parameters.
details:
issues:
- path: countryCode
code: invalid_format
message: Expected a 2-letter country code.
'401':
description: The API key is missing, invalid, or expired.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: unauthorized
message: Unauthorized
details: {}
'402':
description: The account does not have enough balance for this request.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: insufficient_balance
message: Insufficient proxy traffic balance.
details: {}
'403':
description: The API key does not grant access to this operation.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: forbidden
message: Forbidden
details: {}
'404':
description: The requested resource is not available.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: not_found
message: Requested resource was not found.
details: {}
'409':
description: The authenticated account is not configured for this product.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: account_not_configured
message: Account is not configured for proxy products.
details: {}
'500':
description: An unexpected server error occurred.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: internal_error
message: Internal Server Error
details: {}
'502':
description: An upstream service failed while processing the request.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- unauthorized
- forbidden
- invalid_request
- insufficient_balance
- account_not_configured
- not_found
- settings_in_use
- settings_limit_reached
- session_not_active
- connection_in_use
- upstream_error
- internal_error
message:
type: string
example: Invalid request parameters.
details:
type: object
properties:
target:
example: settings.id
type: string
recoveryHint:
example: >-
Stop the active session before reusing these
settings.
type: string
activeSessionId:
example: 58e531ee-16ca-49d0-8722-b425d154cc10
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
nextOperationId:
example: stopBrowserSession
type: string
requestId:
example: a1901a29e82a999f-CDG
type: string
upstreamStatus:
example: 503
type: integer
minimum: 100
maximum: 599
failureStage:
example: provider_browser_start
type: string
diagnosticCode:
example: token_sign_failed
type: string
additionalProperties: {}
required:
- code
- message
- details
required:
- error
example:
error:
code: upstream_error
message: Failed to fetch data from an upstream service.
details:
upstreamStatus: 503
components:
securitySchemes:
apiKeyHeader:
type: apiKey
in: header
name: X-Api-Key
description: Client API key for the authenticated account.
````