superagnt-com Web: Search API

openapi: 3.2.0
info:
  title: 'superagnt Web: 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: 'Web: Search'
  description: Search the web and optionally scrape the results.
paths:
  /v1/data/web/search:
    post:
      operationId: search
      summary: Search the web
      description: Runs a web search and returns result URLs + snippets — cheap; use this first and read the snippets. Add `scrapeOptions` ONLY when you actually need the full text of the pages, because it then downloads and bills EVERY result — keep `limit` small when you do (a few results, not dozens). To read specific pages, prefer searching first and then scraping just the one or two URLs you chose. Supports web, news, and image sources.
      tags:
      - 'Web: Search'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  maxLength: 500
                  description: The search query.
                limit:
                  type: integer
                  description: Number of results per source. Default 10.
                  minimum: 1
                  maximum: 100
                  default: 10
                sources:
                  type: array
                  description: Which result sources to query. Defaults to ['web']. Each entry is a preset string or an object with a `type`.
                  items:
                    oneOf:
                    - type: string
                      enum:
                      - web
                      - news
                      - images
                    - type: object
                      required:
                      - type
                      properties:
                        type:
                          type: string
                          enum:
                          - web
                          - news
                          - images
                categories:
                  type: array
                  items:
                    type: string
                    enum:
                    - github
                    - research
                    - pdf
                  description: Restrict results to these categories.
                tbs:
                  type: string
                  description: Time-based search filter (e.g. 'qdr:d' for past day).
                location:
                  type: string
                  description: Geo-target for the search (e.g. 'San Francisco, California, United States').
                country:
                  type: string
                  description: ISO country code. Default 'US'.
                  default: US
                includeDomains:
                  type: array
                  items:
                    type: string
                  description: Only return results from these hostnames (mutually exclusive with excludeDomains).
                excludeDomains:
                  type: array
                  items:
                    type: string
                  description: Exclude results from these hostnames (mutually exclusive with includeDomains).
                timeout:
                  type: integer
                  description: Request timeout in milliseconds. Default 60000.
                  minimum: 1000
                scrapeOptions:
                  type: object
                  description: When provided, each result is also scraped and its content returned. Accepts the same content options as /scrape (e.g. `formats`, `onlyMainContent`). Increases cost because every result is fetched.
                  properties:
                    formats:
                      type: array
                      items: {}
                      description: Output formats for each scraped result (e.g. ['markdown']).
                    onlyMainContent:
                      type: boolean
                      default: true
            example:
              query: best open source vector databases
              limit: 5
      responses:
        '200':
          description: Search results, optionally including scraped page content.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request — missing `query` or invalid parameter.
        '401':
          description: Unauthorized.
        '402':
          description: Insufficient balance.
        '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_...'