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

# Fetch

> Fetches a target page through Web Data and returns the fetched HTML. Upstream scrape failures return structured v2 JSON errors with message "Failed to scrape the URL" and safe metadata only. Use this for page retrieval. Do not use it for usage reporting; use getWebDataUsage or getAccountUsage instead.

<Warning>
  This playground sends real production requests and can consume Web Data balance.
</Warning>


## OpenAPI

````yaml api-reference/openapi.json POST /v2/web-data/fetch
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/fetch:
    post:
      tags:
        - Web Data
      summary: Fetch a page with Web Data
      description: >-
        Fetches a target page through Web Data and returns the fetched HTML.
        Upstream scrape failures return structured v2 JSON errors with message
        "Failed to scrape the URL" and safe metadata only. Use this for page
        retrieval. Do not use it for usage reporting; use getWebDataUsage or
        getAccountUsage instead.
      operationId: fetchWebData
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: Target page URL to fetch through Web Data.
                  example: https://example.com
                countryCode:
                  description: 2-letter country code for the request exit location.
                  example: US
                  type: string
                  pattern: ^[a-zA-Z]{2}$
                city:
                  description: City for the request exit location.
                  example: New York
                  type: string
                  minLength: 1
                difficulty:
                  description: Access difficulty pool. Defaults to the upstream default.
                  example: low
                  type: string
                  enum:
                    - low
                    - medium
                cacheMaxAgeDays:
                  description: Maximum age of cached content in days.
                  example: 0
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
              required:
                - url
              additionalProperties: false
      responses:
        '200':
          description: Fetched page HTML.
          content:
            application/json:
              schema:
                type: object
                properties:
                  html:
                    type: string
                    description: HTML content returned by the target page.
                  sourceUrl:
                    type: string
                    description: Target URL that was fetched.
                    example: https://example.com
                  fetchedAt:
                    type: string
                    description: ISO 8601 timestamp when the fetch completed.
                    example: '2026-06-10T12:00:00.000Z'
                required:
                  - html
                  - sourceUrl
                  - fetchedAt
              example:
                html: >-
                  <!doctype html><html><head><title>Example
                  Domain</title></head><body>...</body></html>
                sourceUrl: https://example.com
                fetchedAt: '2026-06-10T12:00:00.000Z'
        '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: country
                        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: Rotating proxy credential 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.

````