FastAF Serp API

openapi: 3.2.0
info:
  title: FastAF Serp 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: SERP
paths:
  /v1/serp:
    get:
      tags:
      - SERP
      summary: Search engine results
      description: 'Live Google search results as JSON: organic results with title, link and snippet, plus related blocks when Google shows them.'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Provider response.
          headers:
            X-FastAF-Credits-Used:
              schema:
                type: integer
            X-FastAF-Cost-Version:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  organic_results:
                    type: array
                    items:
                      type: object
                      properties:
                        position:
                          type: number
                        title:
                          type: string
                        link:
                          type: string
                        snippet:
                          type: string
                      additionalProperties: true
                additionalProperties: true
              example:
                organic_results:
                - position: 1
                  title: Best espresso machines for home brewing
                  link: https://example.com/guides/espresso-machines
                  snippet: Compare compact espresso machines by pressure, grinder and milk-steaming features.
            text/html:
              schema:
                type: string
        '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: 5
      x-fastaf-cost-version: v1
      operationId: getSerp
      parameters:
      - name: query
        in: query
        required: true
        description: Required Google search text; supports operators such as site:example.com and intitle:coffee. No default. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: results
        in: query
        required: false
        description: Maximum results retained by FastAF, integer 1-100. Omit for the full returned page. Google supplies up to 10 per page; use page for more, not a larger results value. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: page
        in: query
        required: false
        description: Zero-based Google results page, integer 0-100; default 0. Each page is a separate request. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: integer
          minimum: 0
      - name: advance_search
        in: query
        required: false
        description: 'Include advanced Google result features/snippets when true; true/false, default false. False: 5 credits; true: 10 credits per request.'
        schema:
          type: boolean
      - name: mob_search
        in: query
        required: false
        description: Request mobile rather than desktop Google results; true/false, default false. FastAF does not add a mobile surcharge. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: boolean
      - name: html
        in: query
        required: false
        description: Return raw source HTML instead of parsed JSON when true; true/false, default false. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: boolean
      - name: deep_scrape
        in: query
        required: false
        description: Fetch content from organic-result destination pages as well as the SERP; true/false, default false. Use with advance_search=false; no FastAF surcharge. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: boolean
      - name: domain
        in: query
        required: false
        description: Google host to search, e.g. google.com or google.co.uk; default google.com. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: country
        in: query
        required: false
        description: Two-letter search country code, e.g. us, uk or fr; default us. Localizes results, not a scrape proxy selection. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: language
        in: query
        required: false
        description: Result/interface language code, e.g. en, es, fr or de; default en. Use lr, where supported, to restrict document languages. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: location
        in: query
        required: false
        description: City-level search origin, e.g. Austin, Texas, United States; omit for source-default location. Cannot be combined with uule. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: uule
        in: query
        required: false
        description: Google's encoded geographic search token, copied from a Google URL. Omit for no explicit token; do not combine with location where supported. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: cr
        in: query
        required: false
        description: 'Restrict documents by country: countryFR or countryFR|countryDE. Omitted: no explicit country restriction (unlike country, which localizes the search). No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
      - name: lr
        in: query
        required: false
        description: 'Document-language filter: lang_en or a pipe-separated list such as lang_en|lang_fr. Omitted: no explicit language restriction. No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
      - name: tbs
        in: query
        required: false
        description: 'Google filter expression, e.g. qdr:d for the past day or qdr:w for the past week. Omitted: no explicit time/advanced filter. No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
      - name: safe
        in: query
        required: false
        description: 'Adult-content filter: active enables SafeSearch; off disables it (default off). No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
      - name: nfpr
        in: query
        required: false
        description: 'Spelling correction: string 1 excludes automatically corrected queries; 0 allows them (default 0). No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
      - name: filter
        in: query
        required: false
        description: 'Duplicate/omitted-result filtering: string 1 enables it (default); 0 includes similar and normally omitted results. No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
      - name: ludocid
        in: query
        required: false
        description: 'Google business listing CID as a decimal string, copied from a Google local result. Omitted: no specific business selected. No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
      - name: lsig
        in: query
        required: false
        description: Opaque Google local-listing signature used with a business/knowledge-panel lookup; copy from a Google URL. No default. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: kgmid
        in: query
        required: false
        description: Google Knowledge Graph entity ID, e.g. /m/09c7w0; may override other search filters except page/results. No default. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: si
        in: query
        required: false
        description: Opaque Google cached-search/knowledge-panel tab token; may override other filters except page/results. No default. No additional credits; 5 per request, or 10 with advance_search=true.
        schema:
          type: string
          maxLength: 8192
      - name: ibp
        in: query
        required: false
        description: 'Google layout/expansion expression, e.g. gwp;0,7 for a ludocid lookup. Omitted: standard results layout. No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
      - name: uds
        in: query
        required: false
        description: 'Opaque Google results-filter token copied from a Google search URL. Omitted: no extra token filter; do not invent a token. No additional credits; 5 per request, or 10 with advance_search=true.'
        schema:
          type: string
          maxLength: 8192
    post:
      tags:
      - SERP
      summary: Search engine results
      description: 'Live Google search results as JSON: organic results with title, link and snippet, plus related blocks when Google shows them.'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Provider response.
          headers:
            X-FastAF-Credits-Used:
              schema:
                type: integer
            X-FastAF-Cost-Version:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  organic_results:
                    type: array
                    items:
                      type: object
                      properties:
                        position:
                          type: number
                        title:
                          type: string
                        link:
                          type: string
                        snippet:
                          type: string
                      additionalProperties: true
                additionalProperties: true
              example:
                organic_results:
                - position: 1
                  title: Best espresso machines for home brewing
                  link: https://example.com/guides/espresso-machines
                  snippet: Compare compact espresso machines by pressure, grinder and milk-steaming features.
            text/html:
              schema:
                type: string
        '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: 5
      x-fastaf-cost-version: v1
      operationId: postSerp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                query:
                  type: string
                  maxLength: 8192
                  description: Required Google search text; supports operators such as site:example.com and intitle:coffee. No default. No additional credits; 5 per request, or 10 with advance_search=true.
                results:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: Maximum results retained by FastAF, integer 1-100. Omit for the full returned page. Google supplies up to 10 per page; use page for more, not a larger results value. No additional credits; 5 per request, or 10 with advance_search=true.
                page:
                  type: integer
                  minimum: 0
                  description: Zero-based Google results page, integer 0-100; default 0. Each page is a separate request. No additional credits; 5 per request, or 10 with advance_search=true.
                advance_search:
                  type: boolean
                  description: 'Include advanced Google result features/snippets when true; true/false, default false. False: 5 credits; true: 10 credits per request.'
                mob_search:
                  type: boolean
                  description: Request mobile rather than desktop Google results; true/false, default false. FastAF does not add a mobile surcharge. No additional credits; 5 per request, or 10 with advance_search=true.
                html:
                  type: boolean
                  description: Return raw source HTML instead of parsed JSON when true; true/false, default false. No additional credits; 5 per request, or 10 with advance_search=true.
                deep_scrape:
                  type: boolean
                  description: Fetch content from organic-result destination pages as well as the SERP; true/false, default false. Use with advance_search=false; no FastAF surcharge. No additional credits; 5 per request, or 10 with advance_search=true.
                domain:
                  type: string
                  maxLength: 8192
                  description: Google host to search, e.g. google.com or google.co.uk; default google.com. No additional credits; 5 per request, or 10 with advance_search=true.
                country:
                  type: string
                  maxLength: 8192
                  description: Two-letter search country code, e.g. us, uk or fr; default us. Localizes results, not a scrape proxy selection. No additional credits; 5 per request, or 10 with advance_search=true.
                language:
                  type: string
                  maxLength: 8192
                  description: Result/interface language code, e.g. en, es, fr or de; default en. Use lr, where supported, to restrict document languages. No additional credits; 5 per request, or 10 with advance_search=true.
                location:
                  type: string
                  maxLength: 8192
                  description: City-level search origin, e.g. Austin, Texas, United States; omit for source-default location. Cannot be combined with uule. No additional credits; 5 per request, or 10 with advance_search=true.
                uule:
                  type: string
                  maxLength: 8192
                  description: Google's encoded geographic search token, copied from a Google URL. Omit for no explicit token; do not combine with location where supported. No additional credits; 5 per request, or 10 with advance_search=true.
                cr:
                  type: string
                  maxLength: 8192
                  description: 'Restrict documents by country: countryFR or countryFR|countryDE. Omitted: no explicit country restriction (unlike country, which localizes the search). No additional credits; 5 per request, or 10 with advance_search=true.'
                lr:
                  type: string
                  maxLength: 8192
                  description: 'Document-language filter: lang_en or a pipe-separated list such as lang_en|lang_fr. Omitted: no explicit language restriction. No additional credits; 5 per request, or 10 with advance_search=true.'
                tbs:
                  type: string
                  maxLength: 8192
                  description: 'Google filter expression, e.g. qdr:d for the past day or qdr:w for the past week. Omitted: no explicit time/advanced filter. No additional credits; 5 per request, or 10 with advance_search=true.'
                safe:
                  type: string
                  maxLength: 8192
                  description: 'Adult-content filter: active enables SafeSearch; off disables it (default off). No additional credits; 5 per request, or 10 with advance_search=true.'
                nfpr:
                  type: string
                  maxLength: 8192
                  description: 'Spelling correction: string 1 excludes automatically corrected queries; 0 allows them (default 0). No additional credits; 5 per request, or 10 with advance_search=true.'
                filter:
                  type: string
                  maxLength: 8192
                  description: 'Duplicate/omitted-result filtering: string 1 enables it (default); 0 includes similar and normally omitted results. No additional credits; 5 per request, or 10 with advance_search=true.'
                ludocid:
                  type: string
                  maxLength: 8192
                  description: 'Google business listing CID as a decimal string, copied from a Google local result. Omitted: no specific business selected. No additional credits; 5 per request, or 10 with advance_search=true.'
                lsig:
                  type: string
                  maxLength: 8192
                  description: Opaque Google local-listing signature used with a business/knowledge-panel lookup; copy from a Google URL. No default. No additional credits; 5 per request, or 10 with advance_search=true.
                kgmid:
                  type: string
                  maxLength: 8192
                  description: Google Knowledge Graph entity ID, e.g. /m/09c7w0; may override other search filters except page/results. No default. No additional credits; 5 per request, or 10 with advance_search=true.
                si:
                  type: string
                  maxLength: 8192
                  description: Opaque Google cached-search/knowledge-panel tab token; may override other filters except page/results. No default. No additional credits; 5 per request, or 10 with advance_search=true.
                ibp:
                  type: string
                  maxLength: 8192
                  description: 'Google layout/expansion expression, e.g. gwp;0,7 for a ludocid lookup. Omitted: standard results layout. No additional credits; 5 per request, or 10 with advance_search=true.'
                uds:
                  type: string
                  maxLength: 8192
                  description: 'Opaque Google results-filter token copied from a Google search URL. Omitted: no extra token filter; do not invent a token. No additional credits; 5 per request, or 10 with advance_search=true.'
              required:
              - query
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