Search Endpoint Reference
Primary semantic retrieval surface for new Exa integrations viaPOST /search.
Canonical Docs Links
- Base docs URL:
https://exa.ai/docs - Search reference:
/reference/search - Search coding-agent reference:
/reference/search-api-guide-for-coding-agents - Search best practices:
/reference/search-best-practices - Content freshness:
/reference/livecrawling-contents
Contents
- Overview
- Request shape
- Search types
- Nested contents options
- Structured output
- Category caveats
- Streaming and response shape
- Critical pitfalls
Overview
Use the search endpoint when you need:- general semantic web retrieval
- category-aware search such as
people,company,news, orfinancial report - synthesized output controlled by
systemPromptandoutputSchema - content extraction attached to search results through the nested
contentsobject
type: "fast" or the /context endpoint rather than inventing category filters like github.
Request Shape
Core Request Parameters
Search Types
Use Exa’s primary search types as latency/quality presets:
Use
auto unless the use case clearly prioritizes real-time speed or deeper reasoning.
outputSchema works across search types, so do not pick a deep variant only because you want structured output.
Nested Contents Options
On the search endpoint, all content-extraction controls live insidecontents.
contents Parameters
Text vs Highlights vs Summary
- Start with one by default:
- Use
highlightsfor agent workflows and multi-step chains - Use
textwhen downstream logic truly needs broad page context - Use
summaryonly when you explicitly want Exa-side per-result synthesis
text, highlights, and summary in one request unless the use case clearly needs multiple views of the same page. summary adds a per-result LLM call, so N results means N extra synthesis steps. highlights: true auto-selects an appropriate excerpt length per page. Only set highlights.maxCharacters for fixed budgets, and avoid values below about 400 because they usually truncate too aggressively for downstream LLM use.
Structured Output
systemPrompt and outputSchema do different jobs:
systemPromptcontrols behavior, emphasis, and source preferencesoutputSchemacontrols the shape ofoutput.content
Category Caveats
Stick to documented category values only. Do not invent categories such asgithub, documentation, qa, or pdf. For coding queries, prefer type: "fast" or the /context endpoint instead of category filters.
The specialized company and people categories have extra restrictions:
peopledoes not support date or crawl-date filters, and does not supportexcludeDomains- for
people,includeDomainsonly accepts LinkedIn domains companydoes not support date or crawl-date filterscompanysupportsexcludeDomains- unsupported category/filter combinations return a 400 error
people search in particular, push more of the filtering logic into the natural-language query.
Streaming and Response Shape
Withstream: true, the search endpoint returns text/event-stream instead of a single JSON payload. Robust consumers should branch on the chunk type. Current public chunk types are text-delta, grounding, results, stream-reset, done, and error.
Non-streaming responses typically include:
requestIdresults- optional
output costDollarssearchTime
output.grounding when using structured or synthesized output.
Critical Pitfalls
- Do not place
text,highlights, orsummaryat the top level on/search. - Do not stack
text,highlights, andsummaryon the same call. Pick one.summaryfires a per-result LLM call. - Do not use
tokensNumon/search; usecontents.text.maxCharactersif you need to cap text size. - Treat
useAutoprompt,numSentences, andhighlightsPerUrlas deprecated; do not add them to new examples. - Prefer
contents.maxAgeHoursover olderlivecrawlguidance. - Stick to documented
categoryvalues. Do not invent values such asgithub,documentation,qa, orpdf. - Be careful with specialized categories, especially
peopleandcompany, because some filters are invalid there.