FastAF Scrape API

openapi: 3.2.0
info:
  title: FastAF Scrape API
  version: v1
  contact:
    email: support@fastaf.co
    url: https://fastaf.co/docs/#x402
  description: 'FastAF is a web data API for AI agents: Google SERP, Maps, ecommerce, web scraping, AI extraction, screenshots, news, jobs, research, public profiles and video transcripts. Use prepaid API keys or account-free x402 v2 payments.'
  x-guidance: 'Use GET /x402/v1/{endpoint} with query parameters (not POST or a JSON body). Choose serp for Google search, maps for places, news/shopping/scholar/jobs for specialized search, ai for Google AI Mode, amazon/youtube for their resource variants, linkedin/x for public profiles, walmart/zillow/ebay for structured commerce or listings, scrape for public HTML or markdown, and screenshot for images. Use the dedicated zillow and ebay endpoints instead of scrape for those sites. The q and lang aliases are accepted for query (search_query on YouTube) and language. Send a valid unpaid request first; read the x402 v2 PAYMENT-REQUIRED header, sign with an x402 client such as @x402/fetch, and retry the identical URL with PAYMENT-SIGNATURE. USDC payment uses the network and amount in that live challenge; no API-key authentication is needed. Only successful results are settled; inspect PAYMENT-RESPONSE for the receipt. Prices here are decimal USD, while the challenge uses USDC atomic units (six decimals). Dynamic prices depend on advance_search (serp), resource (amazon/youtube), or rendering, proxies/country and AI extraction (scrape). Scrape site defaults, including Booking rendering and Reddit feed mode, are applied before quoting. A bare unsigned URL returns a default-variant discovery quote only: add valid parameters and request a new challenge before paying. Unpaid HEAD probes also return PAYMENT-REQUIRED with no body; use GET, not HEAD, to pay for data. Invalid parameterized requests and blocked targets return 400; payment headers never bypass validation. Never reuse a settled signature for a new call. Respect Retry-After on rate/capacity errors. For the separate prepaid-key API and authenticated credit-pack top-up, see /v1/openapi.json. Get a free API key at https://fastaf.co/signup/ with an email address, terms acceptance and browser verification. No card is required. POST /public/signup sends an email confirmation link and sets a dashboard session cookie; it does not return an API key. Follow the emailed GET /public/signin/{token} link, then create a key in the dashboard (POST /v1/keys with the session cookie). The key is shown only once. Email confirmation unlocks 2 free calls per account in total, not per day, shared across all keys and all offered REST/MCP endpoints, valid for 12 months; failed calls restore their slot. Unverified trial accounts receive email_verification_required (403) before any data call or trial reservation. Signups are limited per IPv4 /24 or IPv6 /64 network per UTC day (default 3); 429 means retry after the reset. GET /v1/usage reports free_requests_remaining separately from balance_credits. POST /v1/signup is retired and always returns 410 signup_disabled. Agents without an inbox can use /x402/v1/{endpoint} without an account.'
  x-signup-guidance: Get a free API key at https://fastaf.co/signup/ with an email address, terms acceptance and browser verification. No card is required. POST /public/signup sends an email confirmation link and sets a dashboard session cookie; it does not return an API key. Follow the emailed GET /public/signin/{token} link, then create a key in the dashboard (POST /v1/keys with the session cookie). The key is shown only once. Email confirmation unlocks 2 free calls per account in total, not per day, shared across all keys and all offered REST/MCP endpoints, valid for 12 months; failed calls restore their slot. Unverified trial accounts receive email_verification_required (403) before any data call or trial reservation. Signups are limited per IPv4 /24 or IPv6 /64 network per UTC day (default 3); 429 means retry after the reset. GET /v1/usage reports free_requests_remaining separately from balance_credits. POST /v1/signup is retired and always returns 410 signup_disabled. Agents without an inbox can use /x402/v1/{endpoint} without an account.
servers:
- url: https://api.fastaf.co
tags:
- name: Scrape
paths:
  /v1/scrape:
    get:
      tags:
      - Scrape
      summary: Web page scraping
      description: Public page HTML, markdown, links, images or AI extraction/summary; optional JavaScript rendering. Blocked, empty or incomplete results are not settled.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Provider response.
          headers:
            X-FastAF-Credits-Used:
              schema:
                type: integer
            X-FastAF-Cost-Version:
              schema:
                type: string
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
              example: '# Example Domain


                This domain is for use in documentation examples.'
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type:
                - object
                - array
                additionalProperties: true
            image/*:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      x-fastaf-credit-cost:
        default: 1
        dynamic: 5
        premium: 10
        dynamicAndPremium: 25
        challenge: 10
        aiSurcharge: 10
      x-fastaf-cost-version: v1
      operationId: getScrape
      parameters:
      - name: url
        in: query
        required: true
        description: 'Required public HTTP(S) page URL. Zillow/eBay URLs are rejected without charge: use their dedicated endpoints. Booking defaults to rendering; Reddit uses a best-effort public feed (1 credit), ignoring rendering/proxy/wait/session/header options. Normal base cost: 1 credit; rendered Booking defaults cost 5. Other selected modes/AI can increase cost.'
        schema:
          type: string
          format: uri
          pattern: ^https?://
      - name: dynamic
        in: query
        required: false
        description: 'Render JavaScript before extracting content; true/false. FastAF default false, except booking.com defaults true with wait=8000. Ignored for Reddit feeds. Base cost: 1 credit without rendering, 5 with rendering, or 25 with rendering plus premium/country; AI adds 10.'
        schema:
          type: boolean
      - name: js_rendering
        in: query
        required: false
        description: 'Alias for dynamic with identical defaults and pricing. Boolean; cannot disagree with dynamic. Ignored for Reddit feeds. Base cost: 1 credit without rendering, 5 with rendering, or 25 with rendering plus premium/country; AI adds 10.'
        schema:
          type: boolean
      - name: premium
        in: query
        required: false
        description: 'Use residential proxies; true/false, default false. Cannot combine true with challenge_mode. Ignored for Reddit feeds. Base cost with premium=true or any country: 10 credits, 25 with dynamic; AI adds 10.'
        schema:
          type: boolean
      - name: custom_headers
        in: query
        required: false
        description: Boolean upstream header-forwarding flag, default false; NOT a header map. FastAF does not forward caller HTTP headers, cookies or Authorization to the target, so this cannot customize them. Ignored for Reddit feeds. No additional credits; selected rendering/proxy/AI options determine the request cost.
        schema:
          type: boolean
      - name: wait
        in: query
        required: false
        description: 'Extra browser loading delay in milliseconds, integer 0-35000, for dynamic rendering. Omitted: no explicit extra delay, except rendered booking.com defaults to 8000. Does not enable rendering; ignored for Reddit feeds. No additional credits; selected rendering/proxy/AI options determine the request cost.'
        schema:
          type: integer
          minimum: 0
          maximum: 35000
      - name: country
        in: query
        required: false
        description: 'Proxy exit country as a two-letter ISO 3166-1 code, e.g. us, gb or de. Omit for no country targeting. Selecting any country uses premium-tier pricing even if premium=false; incompatible with challenge_mode. Ignored for Reddit feeds. Base cost with premium=true or any country: 10 credits, 25 with dynamic; AI adds 10.'
        schema:
          type: string
          maxLength: 8192
      - name: session_number
        in: query
        required: false
        description: Reusable proxy session identifier, e.g. 12345. Repeat it to request the same proxy IP; expires after 60 seconds of inactivity. Omit to rotate normally. Ignored for Reddit feeds; not a FastAF login session. No additional credits; selected rendering/proxy/AI options determine the request cost.
        schema:
          type: string
          maxLength: 8192
      - name: image
        in: query
        required: false
        description: 'Enable fetching image URLs; true/false, default false. Not a screenshot: use /screenshot for captures, or formats=images to extract page image links. No additional credits; selected rendering/proxy/AI options determine the request cost.'
        schema:
          type: boolean
      - name: formats
        in: query
        required: false
        description: 'One output format: html (default), links, markdown, summary or images. summary is AI-generated; links/images extract page URLs. Reddit supports html/markdown only. AI extraction (ai_query, ai_extract_rules or formats=summary) adds 10 credits once per request, even when combined; other formats add none.'
        schema:
          type: string
          enum:
          - html
          - links
          - markdown
          - summary
          - images
      - name: ai_query
        in: query
        required: false
        description: Natural-language extraction prompt, e.g. Return the product price and currency. Omit for no prompt-based extraction. Not supported for Reddit feeds. AI extraction (ai_query, ai_extract_rules or formats=summary) adds 10 credits once per request, even when combined; other formats add none.
        schema:
          type: string
          maxLength: 8192
      - name: ai_extract_rules
        in: query
        required: false
        description: JSON-encoded extraction instructions as a STRING, e.g. {"price":"product price","currency":"currency code"}; not a nested JSON object. Omit for no rule-based extraction. Not supported for Reddit feeds. AI extraction (ai_query, ai_extract_rules or formats=summary) adds 10 credits once per request, even when combined; other formats add none.
        schema:
          type: string
          maxLength: 8192
      - name: type
        in: query
        required: false
        description: 'Non-HTML target format: image, pdf or pbf (Protocolbuffer Binary Format). Omit for normal page scraping. This selects a binary resource, not a screenshot or an output format conversion. No additional credits; selected rendering/proxy/AI options determine the request cost.'
        schema:
          type: string
          enum:
          - image
          - pdf
          - pbf
      - name: challenge_mode
        in: query
        required: false
        description: 'Browser-verification handling mode; true/false, default false. Uses its own rendering/proxies; cannot combine with dynamic=true, premium=true or country. Ignored for Reddit feeds. When enabled: 10 base credits; AI adds 10.'
        schema:
          type: boolean
    post:
      tags:
      - Scrape
      summary: Web page scraping
      description: Public page HTML, markdown, links, images or AI extraction/summary; optional JavaScript rendering. Blocked, empty or incomplete results are not settled.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Provider response.
          headers:
            X-FastAF-Credits-Used:
              schema:
                type: integer
            X-FastAF-Cost-Version:
              schema:
                type: string
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
              example: '# Example Domain


                This domain is for use in documentation examples.'
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type:
                - object
                - array
                additionalProperties: true
            image/*:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      x-fastaf-credit-cost:
        default: 1
        dynamic: 5
        premium: 10
        dynamicAndPremium: 25
        challenge: 10
        aiSurcharge: 10
      x-fastaf-cost-version: v1
      operationId: postScrape
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                url:
                  type: string
                  format: uri
                  pattern: ^https?://
                  description: 'Required public HTTP(S) page URL. Zillow/eBay URLs are rejected without charge: use their dedicated endpoints. Booking defaults to rendering; Reddit uses a best-effort public feed (1 credit), ignoring rendering/proxy/wait/session/header options. Normal base cost: 1 credit; rendered Booking defaults cost 5. Other selected modes/AI can increase cost.'
                dynamic:
                  type: boolean
                  description: 'Render JavaScript before extracting content; true/false. FastAF default false, except booking.com defaults true with wait=8000. Ignored for Reddit feeds. Base cost: 1 credit without rendering, 5 with rendering, or 25 with rendering plus premium/country; AI adds 10.'
                js_rendering:
                  type: boolean
                  description: 'Alias for dynamic with identical defaults and pricing. Boolean; cannot disagree with dynamic. Ignored for Reddit feeds. Base cost: 1 credit without rendering, 5 with rendering, or 25 with rendering plus premium/country; AI adds 10.'
                premium:
                  type: boolean
                  description: 'Use residential proxies; true/false, default false. Cannot combine true with challenge_mode. Ignored for Reddit feeds. Base cost with premium=true or any country: 10 credits, 25 with dynamic; AI adds 10.'
                custom_headers:
                  type: boolean
                  description: Boolean upstream header-forwarding flag, default false; NOT a header map. FastAF does not forward caller HTTP headers, cookies or Authorization to the target, so this cannot customize them. Ignored for Reddit feeds. No additional credits; selected rendering/proxy/AI options determine the request cost.
                wait:
                  type: integer
                  minimum: 0
                  maximum: 35000
                  description: 'Extra browser loading delay in milliseconds, integer 0-35000, for dynamic rendering. Omitted: no explicit extra delay, except rendered booking.com defaults to 8000. Does not enable rendering; ignored for Reddit feeds. No additional credits; selected rendering/proxy/AI options determine the request cost.'
                country:
                  type: string
                  maxLength: 8192
                  description: 'Proxy exit country as a two-letter ISO 3166-1 code, e.g. us, gb or de. Omit for no country targeting. Selecting any country uses premium-tier pricing even if premium=false; incompatible with challenge_mode. Ignored for Reddit feeds. Base cost with premium=true or any country: 10 credits, 25 with dynamic; AI adds 10.'
                session_number:
                  type: string
                  maxLength: 8192
                  description: Reusable proxy session identifier, e.g. 12345. Repeat it to request the same proxy IP; expires after 60 seconds of inactivity. Omit to rotate normally. Ignored for Reddit feeds; not a FastAF login session. No additional credits; selected rendering/proxy/AI options determine the request cost.
                image:
                  type: boolean
                  description: 'Enable fetching image URLs; true/false, default false. Not a screenshot: use /screenshot for captures, or formats=images to extract page image links. No additional credits; selected rendering/proxy/AI options determine the request cost.'
                formats:
                  type: string
                  enum:
                  - html
                  - links
                  - markdown
                  - summary
                  - images
                  description: 'One output format: html (default), links, markdown, summary or images. summary is AI-generated; links/images extract page URLs. Reddit supports html/markdown only. AI extraction (ai_query, ai_extract_rules or formats=summary) adds 10 credits once per request, even when combined; other formats add none.'
                ai_query:
                  type: string
                  maxLength: 8192
                  description: Natural-language extraction prompt, e.g. Return the product price and currency. Omit for no prompt-based extraction. Not supported for Reddit feeds. AI extraction (ai_query, ai_extract_rules or formats=summary) adds 10 credits once per request, even when combined; other formats add none.
                ai_extract_rules:
                  type: string
                  maxLength: 8192
                  description: JSON-encoded extraction instructions as a STRING, e.g. {"price":"product price","currency":"currency code"}; not a nested JSON object. Omit for no rule-based extraction. Not supported for Reddit feeds. AI extraction (ai_query, ai_extract_rules or formats=summary) adds 10 credits once per request, even when combined; other formats add none.
                type:
                  type: string
                  enum:
                  - image
                  - pdf
                  - pbf
                  description: 'Non-HTML target format: image, pdf or pbf (Protocolbuffer Binary Format). Omit for normal page scraping. This selects a binary resource, not a screenshot or an output format conversion. No additional credits; selected rendering/proxy/AI options determine the request cost.'
                challenge_mode:
                  type: boolean
                  description: 'Browser-verification handling mode; true/false, default false. Uses its own rendering/proxies; cannot combine with dynamic=true, premium=true or country. Ignored for Reddit feeds. When enabled: 10 base credits; AI adds 10.'
              required:
              - url
components:
  responses:
    BadGateway:
      description: The upstream request failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: The account has insufficient credits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: A rate or concurrency limit was reached.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The account is suspended or email verification is required before data calls.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: A valid bearer API key is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The service is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    GatewayTimeout:
      description: The upstream request timed out.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    sessionCookie:
      type: apiKey
      in: cookie
      name: fastaf_session