Skip to main content
POST
Search the web (JSON body)

Authorizations

x-api-key
string
header
required

API key from the API Console.

Body

application/json
q
string
required

Search query string. Same semantics as the GET q parameter.

limit
integer

Maximum number of results to return. When omitted, a single-query search returns 10–40 results picked to fit the query (fewer for a site or a fact, more for news, lists, documentation and research); 20 with offset or for multi-query. Set limit for a fixed count.

Required range: 1 <= x <= 100
offset
integer
default:0

Number of results to skip for pagination.

Required range: x >= 0
searchMode
enum<string>
default:auto

Search effort control. auto (default) sets the effort per query automatically — simple lookups resolve fast, complex questions get deeper treatment. The fixed modes pin an effort level: instant puts speed first, returns at most 10 results and no page content, and is never chosen by auto. low-cost caps the work done per request for budget-constrained callers. fast returns results in about 2 seconds. balanced is everyday web search, about 4–5 seconds. deep searches from multiple angles with spell correction, about 6.5 seconds. exhaustive is Andi's most thorough mode: more sources and more time, up to about 15 seconds; for a question with several parts or steps it searches each part. Deeper modes add query expansion, follow-up searches fanned out from initial results, and stronger reranking. Requests are billed on outcome-based pricing (see metrics.cost_dollars).

Available options:
auto,
instant,
low-cost,
fast,
balanced,
deep,
exhaustive
effort
enum<string>

Thoroughness dial, independent of searchMode: low favors speed, medium is balanced, high searches from multiple angles with spell correction, max gives the most complete results and also searches each part of a question that has several parts or steps — the same tiers as pinning searchMode to fast, balanced, deep, and exhaustive respectively. An explicit searchMode always wins over effort. With the default auto mode, an explicit effort pins its equivalent mode. Omit for the adaptive default. Invalid values return a 400 listing the valid tiers.

Available options:
low,
medium,
high,
max
reranker
enum<string>
default:auto

Semantic reranker size hint. small is the lightest and fastest; medium and above apply stronger relevance scoring but need a deeper searchMode and may be clamped by the request's time and cost budget (for example, xl needs deep or exhaustive). auto (default) selects a tier automatically based on the query and search mode.

Available options:
auto,
small,
medium,
large,
xl
intent
string

Force a specific search intent. When not set, the API auto-detects intent from the query. Accepts common aliases like search, news, video, images, weather, wiki, code, recipe, place, time, and others.

format
enum<string>
default:json

Response format. json returns a JSON object. context returns results as markdown text, suitable for passing to language models.

Available options:
json,
context
metadata
enum<string>
default:basic

Level of metadata to include. basic includes standard search metrics. full includes extended metadata with content type details and reader data on results.

Available options:
basic,
full
extracts
boolean
default:false

Include text extracts from result pages in the response. Defaults to true when format=context, content=true or content=focused; pass extracts=false to turn them off in those cases. Also returned by default with metadata=full.

content
default:false

Include each result's full page text, in reader.markdown (or reader.content when the page has no markdown version). true returns the head of each page. "focused" returns the parts of each page that answer the query, in page order under section headings; it is billed and capped like true and falls back to the normal page text when no focused text can be built. Any other value is treated as false. Also turns on extracts unless extracts=false is passed. Adds time and cost; deeper modes allow more time.

enrichContent
boolean
default:false
deprecated

Deprecated alias of content.

maxContentLength
integer

Maximum number of characters of page text to return per result. Only applies when content is true.

preset
enum<string>

Named set of defaults: app (the API's ordinary defaults; used for direct calls) or agent (context format, focused page content, extracts, a 16,000-token budget; used by the MCP server and CLI). A preset fills only parameters you did not send, so any parameter you send wins. The reply states the preset when one was chosen (preset in JSON, a preset line in the context frontmatter).

Available options:
app,
agent
maxTokens
integer

Token budget for the results (1,000 to 200,000). Results with page content fill it first, then results with extracts, then snippets; results that do not fit are dropped from the bottom, keeping rank order, and any result shown in part carries truncated, shown_words and total_words. Default 16,000 with format=context and content=focused (24,000 on deep and exhaustive); on other output it applies only when sent.

Required range: 1000 <= x <= 200000
timeout
integer

Target time in milliseconds for ranked results (1000–30000). It is a target, not a hard ceiling. Omit it for the mode's normal speed; a larger value (e.g. 30000) lets slower sources run longer, so deep/exhaustive searches can take close to that long. The search may run a little past it when it needs a moment more to return a useful page. Requested page text (content/extracts) is fetched afterward, on top of the target. Values below 1000 are raised to 1000; values above 30000 are lowered to 30000; 0, empty or non-numeric values are ignored. With searchMode=auto (the default), a timeout steps the resolved mode down to the richest one that fits it. An explicit searchMode is always honored.

Required range: 1000 <= x <= 30000
safe
enum<string>
default:off

Safe search filtering level. off disables filtering, moderate filters most explicit content, strict applies maximum filtering.

Available options:
off,
moderate,
strict
country
string
default:US

Two-letter ISO 3166-1 country code to localize results. When you name a country, its main languages also count as target languages for ranking and for languageMode=strict. It does not narrow what Andi retrieves.

sourceCountry
string

Two-letter ISO 3166-1 country code to restrict results to sources from this country. Unlike country, which biases results by locale, sourceCountry excludes results from other countries.

language
string

Language tag for the search, up to 13 characters. Accepts a primary language with optional region or script subtags, for example en, de, zh-Hans or es-419; matching uses the primary subtag. Omit it and Andi detects the query language. A language you state is used for language filtering, ranking, reranking and page retrieval. The lang: query operator takes precedence. The language Andi used is returned in locale.

Maximum string length: 13
languageMode
enum<string>
default:prefer

How strictly to hold results to the target languages. prefer ranks pages in the query language first. strict also drops pages whose known language is neither a target language nor English; pages with an unknown language are kept. It changes the response only, never what is cached. Target languages are the query language plus, when you name a country, that country's main languages.

Available options:
prefer,
strict
units
enum<string>

Unit system for weather and calculation results. Defaults based on the country parameter — imperial for US, metric for all other countries.

Available options:
metric,
imperial
noCache
boolean
default:false

Bypass cached results and fetch fresh data.

dateRange
enum<string>

Relative date range filter for results.

Available options:
day,
week,
month,
year,
24h,
7d,
30d,
90d,
1y
dateFrom
string<date>

Filter results published on or after this date. Format: YYYY-MM-DD.

dateTo
string<date>

Filter results published on or before this date. Format: YYYY-MM-DD.

includeDomains
string

Comma-separated list of domains to restrict results to. Supports wildcards (*.example.com).

excludeDomains
string

Comma-separated list of domains to exclude from results. Supports wildcards.

includeTerms
string

Comma-separated terms that must appear in results.

excludeTerms
string

Comma-separated terms to exclude from results.

parseOperators
boolean
default:true

Parse query operators (like site:, filetype:, intitle:) from the query string. When disabled, the query is treated as literal text.

Field name for result URLs. Use url to receive the URL field as url instead of the default link. Only affects the /search endpoint.

Available options:
link,
url
imageFormat
enum<string>
default:long

Field naming for image results. long (default) uses full field names. short uses abbreviated field names.

Available options:
short,
long
filetype
string

Filter results by file type.

intitle
string

Filter results to pages with this term in the title.

inurl
string

Filter results to pages with this term in the URL.

intext
string

Filter results to pages with this term in the body text.

latitude
number

Latitude in decimal degrees. Sent in the body to keep coordinates out of HTTP access logs.

longitude
number

Longitude in decimal degrees.

accuracy
number

Location accuracy in meters.

city
string

City name for location-aware queries.

state
string

State or region name.

countryCode
string

Two-letter ISO 3166-1 country code for the caller's location.

postalCode
string

Postal or ZIP code.

timezone
string

IANA timezone, for example America/Los_Angeles.

location
string

Display name for the caller's location, for example "San Francisco, CA".

Response

Search results. JSON by default; LLM-ready markdown with YAML frontmatter when format=context.

results_type
string
required

The type of results returned (e.g., Search, News, Weather, Calculator, TimeZone, Currency, Answer). Determines which optional response sections are present.

answer
string
required

Instant answer for the query when one is found — for example a definition, a weather line or a calculation — otherwise an empty string. On news feeds, a short summary of the headlines when available.

type
string
required

Same as results_type. Indicates the category of results.

title
string
required

Your query text (for a news feed, the feed's description).

results
object[]
required

Array of search results. Only rows with a web address appear; answers with no address (calculator, clock, currency, translation, quote, score) are in answer and their block.

metrics
object
required

Search performance metrics. Always included in the response.

answer_metadata
object

How the answer was made. kind is extractive, instant or llm; citations are the links of the rows it came from; passage is where on the row a quote came from; block (instant answers) names the response field that holds the answer's data (such as weather, calculation, time, currency, quote, score). It points to that field and never copies it. data appears only for a value that exists nowhere else, such as an extracted value.

correctedQuery
string

Spell-corrected query. Present when a misspelling in the original query is detected and corrected — any mode can return it; deep and exhaustive modes run the strongest spell correction.

Related search suggestions. Present on some queries.

topics
string[]

Related topics. Present on some queries.

Related topic names for entity answers.

infobox
object

Facts panel for an entity answer.

aiSummary
object

A pre-written news summary. News feeds return it, and so does search when the query asks for a whole feed (for example "latest technology news" or "hacker news"), but not for a topic inside a feed ("nfl news"). On news feeds the same text is in answer; on search, answer can hold something else, such as a description of the site.

filter_counts
object

Present when an author or publisher filter is set: how many shown results match it and how many have no known author or publisher.

locale
object

The language and country Andi searched for. Present on every search response (not on news feeds). With format=context, the same values appear in the frontmatter as language, language_confidence, language_source, country and local_scope.

Echo of the safe-search state. Present on cache misses. Use it to confirm your safe parameter was honored.

videos
object[]

Video results, when the search found any.

images
object[]

Image results, when the search found any.

news
object[]

News stories, when the search found any. Front pages, section pages, topic pages and listing pages are in categories, not here.

citations
object[]

Rows an answer cites, in the same shape as results. When a search names a whole curated news feed (for example "headlines" or "latest news from hacker news") and the response carries the feed's aiSummary, this lists the stories the summary cites in the summary's order, then the feed's other stories, up to limit. Left out when empty. Not on /api/v1/news.

categories
object[]

News front pages, section pages, topic or tag pages, listing pages and site-search pages. results still holds them too. Left out when empty. Not on /api/v1/news.

places
object[]

Place and business results, when the search found any.

profiles
object[]

People and entity profiles, when the search found any.

social
object[]

Social posts, when the search found any.

academic
object[]

Scholarly papers, when the search found any.

weather
object

Weather data. Present when the query triggers a weather intent.

calculation
object

Calculation result. Present when the query triggers a calculation intent.

preset
object

Which preset ran, how it was chosen and the defaults it filled in. Present only when a preset was chosen by preset= or by the calling surface (MCP server, CLI).

warnings
string[]

Notes on parts of the request the API adjusted or ignored, for example a limit above 10 lowered to 10 on instant.

time
object

Present when the query is a time or clock query.

currency
object

Present when the query is a currency conversion query.

translation
object

Present when the query is a translation query.

quote
object

Present when the query is a share price query.

score
object

Present when the query is a game score query.