superagnt-com SEO: Search API

openapi: 3.2.0
info:
  title: 'superagnt SEO: Search API'
  description: Unified API for social media data. Access LinkedIn, YouTube, TikTok, X, Instagram, Reddit, and Facebook through a single API key.
  version: 1.0.0
  contact:
    name: superagnt
    url: https://superagnt.com
servers:
- url: https://api.superagnt.com
  description: superagnt API
security:
- ApiKeyAuth: []
tags:
- name: 'SEO: Search'
  description: Live Google search results.
paths:
  /v1/data/seo/serp:
    post:
      operationId: google_search
      summary: Live Google search results
      x-agnt-permission: act
      description: 'Runs a live Google search and returns the ranked results: organic listings with position, title, URL and snippet, plus SERP features (featured snippets, people-also-ask, local pack, AI Overviews). AI Overviews often load asynchronously and come back without their cited sources unless you set `load_async_ai_overview`. Use it to check what ranks for a keyword, verify a page''s position, or find competitor pages. Default depth is 10 results, which is the cheapest shape and right for most checks; raise `depth` only when you truly need deeper pages, since cost scales per 10 results. Search operators (site:, inurl:, filetype:) work but multiply the upstream cost roughly 5x, so use them deliberately. At default depth this is one of the cheapest calls in the source (well under half a cent), so prefer it for quick spot checks.'
      tags:
      - 'SEO: Search'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - keyword
              properties:
                keyword:
                  type: string
                  maxLength: 700
                  description: The search query. Supports Google search operators (site:, inurl:, filetype:), which cost roughly 5x.
                location_code:
                  type: integer
                  description: 'Geo target as a location code. Common values: 2840 United States (default), 2826 United Kingdom, 2124 Canada, 2036 Australia, 2276 Germany, 2250 France, 2724 Spain, 2356 India, 2076 Brazil.'
                  default: 2840
                language_code:
                  type: string
                  description: Two-letter language code, e.g. 'en' (default), 'de', 'es', 'fr', 'pt'.
                  default: en
                device:
                  type: string
                  enum:
                  - desktop
                  - mobile
                  description: Device type to emulate. Default 'desktop'.
                  default: desktop
                depth:
                  type: integer
                  minimum: 10
                  maximum: 700
                  default: 10
                  description: Number of results to return, in steps of 10. Default 10 (cheapest). Each additional 10 results bills as one more results page.
                load_async_ai_overview:
                  type: boolean
                  default: false
                  description: 'Set to true to load AI Overviews that Google renders asynchronously, so the `ai_overview` item comes back with its text and cited sources (`markdown`, `items`, `references`). Left off, an async overview still appears, flagged `asynchronous_ai_overview: true`, but with those fields null: you can tell an overview exists, not what it cites. In the default markdown view, the overview row lists its cited sources as `cited_domains`. Adds up to about 0.36 cents per call (roughly double the default-depth price), charged only when an overview actually had to be loaded; the response''s `meta.costCents` shows what the call billed. Default false.'
            example:
              keyword: best crm for startups
              location_code: 2840
              language_code: en
      responses:
        '200':
          description: Ranked search results with SERP features. `result[0].items` holds the listings.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request or upstream task error.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
        5XX:
          description: Upstream error.
      security:
      - ApiKeyAuth: []
  /v1/data/seo/serp-ai-mode:
    post:
      operationId: google_ai_mode_search
      summary: Google AI Mode results
      x-agnt-permission: act
      description: 'Runs the query through Google''s AI Mode and returns the AI-generated answer with its cited sources and references. Use it to see how Google''s AI answers a question and which pages it cites, which is the core check for answer-engine optimization: is your (or a competitor''s) content being used as a source? Costs about 2x a classic search.'
      tags:
      - 'SEO: Search'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - keyword
              properties:
                keyword:
                  type: string
                  maxLength: 700
                  description: The question or query to run through Google AI Mode.
                location_code:
                  type: integer
                  description: 'Geo target as a location code. Common values: 2840 United States (default), 2826 United Kingdom, 2124 Canada, 2036 Australia, 2276 Germany.'
                  default: 2840
                language_code:
                  type: string
                  description: Two-letter language code, e.g. 'en' (default).
                  default: en
            example:
              keyword: what is the best email warmup tool
      responses:
        '200':
          description: The AI-generated answer with cited sources in `result[0].items`.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request or upstream task error.
        '401':
          description: Unauthorized.
        '429':
          description: Too many requests.
        5XX:
          description: Upstream error.
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Bearer token. Pass your agntdata API key as: Authorization: Bearer agnt_live_...'