Web Search

Perform web searches and optionally scrape the results.

Performs a web search and returns results with optional content scraping.

POST /v1/tools/web_search

Authentication

AuthorizationBearerrequired

API key as bearer token in the Authorization header. Create keys at Manage API Keys.

Headers

Content-Typestringrequired

Must be application/json.

Body

querystringrequired

The search query.

limitintegeroptionalDefault 10

Maximum number of results to return. Range: 1 to 50.

sourcesstring[]optional

Sources to search from.

categoriesobject[]optional

Categories to filter results.

include_domainsstring[]optional

Only include results from these domains.

exclude_domainsstring[]optional

Exclude results from these domains.

tbsstringoptional

Time-based search parameter (e.g., qdr:d for past day, qdr:w for past week).

locationstringoptional

Geographic location for search (e.g., us, uk).

countrystringoptional

Country code for search.

timeoutintegeroptional

Request timeout in milliseconds. Minimum: 1.

ignore_invalid_urlsbooleanoptionalDefault false

Ignore invalid URLs in results.

enterpriseobject[]optional

Enterprise search options.

scrape_optionsobjectoptional

Options for scraping each search result. Accepts every web_scrape option except url; unknown keys are rejected with a 400. The most common ones:

scrape_options.formatsstring[]optional

Output formats for scraped content.

Allowed values:markdownsummaryhtmlrawHtmllinksimagesscreenshotjsonchangeTrackingbrandingaudiovideoquestionhighlights
scrape_options.only_main_contentbooleanoptionalDefault false

Extract only the main content from scraped pages.

Response

idstringoptional

Unique request ID for this call.

data.webWebResult[]optional

Web results. Present when sources includes web (the default).

data.newsNewsResult[]optional

News results. Present when sources includes news.

data.imagesImageResult[]optional

Image results. Present when sources includes images.

warningstringoptional

Set when part of the search could not be completed.

Search Result Shape

interface WebResult {
  url: string;
  title: string;
  description: string;
  // With scrape_options, the scraped page fields of web_scrape:
  markdown?: string;
  html?: string;
  raw_html?: string;
  links?: string[];
  metadata?: { title?: string; description?: string; source_url?: string; url?: string };
}

interface NewsResult {
  title: string;
  snippet: string;
  url: string;
  date: string;
  image_url?: string;
  position: number;
  // With scrape_options, the same scraped page fields as WebResult.
}

interface ImageResult {
  title: string;
  image_url: string;
  url: string;
  image_width: number;
  image_height: number;
  position: number;
}

Use Cases

  • Research automation: Search and gather information programmatically
  • Content aggregation: Collect content from multiple sources
  • Competitive analysis: Monitor mentions and rankings
  • RAG pipelines: Fetch real-time web data for AI context