v1

latestOpenAPI 3.0.32026-07-2644164161.5 KB

Tools API

Web search

Search the web for information about a given query and return relevant results with source URLs.

post/v1/tools/web-search

Request body

querystring

The search query.

topic'general' | 'news'

The search topic category. Use news for current events and news articles, or general for broader web search.

search_depth'basic' | 'advanced'

Controls search comprehensiveness:

basic: Returns fewer but highly relevant results
advanced: Performs a deeper search with more results

chunks_per_sourceinteger

Only applies when search_depth is advanced. Specifies how many text segments to extract from each source. Limited to 3 chunks maximum.

max_resultsinteger

Limits the number of search results returned. Cannot exceed 20 sources.

time_range'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y'

Filters results to content published within the specified time range back from the current date. For example, week or w returns results from the past 7 days.

daysinteger

For news topic searches, specifies how many days of news coverage to include.

include_answerboolean

Whether to include a generated answer to the query in the response. If false, only search results are returned.

include_domainsstring[]

Domains to include in the search. If unset, the search includes all domains.

exclude_domainsstring[]

Domains to exclude from the search. If unset, the search includes all domains.

country'afghanistan' | 'albania' | 'algeria' | 'andorra' | 'angola' | 'argentina' | 'armenia' | 'australia' | 'austria' | 'azerbaijan' | 'bahamas' | 'bahrain' | 'bangladesh' | 'barbados' | 'belarus' | 'belgium' | 'belize' | 'benin' | 'bhutan' | 'bolivia' | 'bosnia and herzegovina' | 'botswana' | 'brazil' | 'brunei' | 'bulgaria' | 'burkina faso' | 'burundi' | 'cambodia' | 'cameroon' | 'canada' | 'cape verde' | 'central african republic' | 'chad' | 'chile' | 'china' | 'colombia' | 'comoros' | 'congo' | 'costa rica' | 'croatia' | 'cuba' | 'cyprus' | 'czech republic' | 'denmark' | 'djibouti' | 'dominican republic' | 'ecuador' | 'egypt' | 'el salvador' | 'equatorial guinea' | 'eritrea' | 'estonia' | 'ethiopia' | 'fiji' | 'finland' | 'france' | 'gabon' | 'gambia' | 'georgia' | 'germany' | 'ghana' | 'greece' | 'guatemala' | 'guinea' | 'haiti' | 'honduras' | 'hungary' | 'iceland' | 'india' | 'indonesia' | 'iran' | 'iraq' | 'ireland' | 'israel' | 'italy' | 'jamaica' | 'japan' | 'jordan' | 'kazakhstan' | 'kenya' | 'kuwait' | 'kyrgyzstan' | 'latvia' | 'lebanon' | 'lesotho' | 'liberia' | 'libya' | 'liechtenstein' | 'lithuania' | 'luxembourg' | 'madagascar' | 'malawi' | 'malaysia' | 'maldives' | 'mali' | 'malta' | 'mauritania' | 'mauritius' | 'mexico' | 'moldova' | 'monaco' | 'mongolia' | 'montenegro' | 'morocco' | 'mozambique' | 'myanmar' | 'namibia' | 'nepal' | 'netherlands' | 'new zealand' | 'nicaragua' | 'niger' | 'nigeria' | 'north korea' | 'north macedonia' | 'norway' | 'oman' | 'pakistan' | 'panama' | 'papua new guinea' | 'paraguay' | 'peru' | 'philippines' | 'poland' | 'portugal' | 'qatar' | 'romania' | 'russia' | 'rwanda' | 'saudi arabia' | 'senegal' | 'serbia' | 'singapore' | 'slovakia' | 'slovenia' | 'somalia' | 'south africa' | 'south korea' | 'south sudan' | 'spain' | 'sri lanka' | 'sudan' | 'sweden' | 'switzerland' | 'syria' | 'taiwan' | 'tajikistan' | 'tanzania' | 'thailand' | 'togo' | 'trinidad and tobago' | 'tunisia' | 'turkey' | 'turkmenistan' | 'uganda' | 'ukraine' | 'united arab emirates' | 'united kingdom' | 'united states' | 'uruguay' | 'uzbekistan' | 'venezuela' | 'vietnam' | 'yemen' | 'zambia' | 'zimbabwe'

Localizes search results to a specific country. Only applies to general topic searches.

streamboolean

Enables streaming of search results as they become available.

Response

Successful response

querystring required

The search query that was submitted.

answerstring

Generated answer based on the search results. Not included if include_answer is false.