Search the web

{
  "operationId": "search",
  "method": "post",
  "path": "/search",
  "summary": "Search the web",
  "description": "Runs a web search and returns results. Pass `scrapeOptions` to also return the full page content of each result in one call. Supports web, news, and image sources.",
  "parameters": [],
  "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": [
    {
      "statusCode": "200",
      "description": "Search results, optionally including scraped page content.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    {
      "statusCode": "400",
      "description": "Bad request — missing `query` or invalid parameter."
    },
    {
      "statusCode": "401",
      "description": "Unauthorized."
    },
    {
      "statusCode": "402",
      "description": "Insufficient balance."
    },
    {
      "statusCode": "429",
      "description": "Too many requests."
    },
    {
      "statusCode": "5XX",
      "description": "Upstream error."
    }
  ]
}