build-with-exa

Build with Exa

Scope

Included by default:

• Core retrieval APIs: search endpoint, contents endpoint, answer endpoint
• Long-running research workflows: Agent API (/agent)
• Async and recurring workflows: Monitors API
• Legacy surface: Websets API (existing integrations only; new collection-building work uses the Agent API)
• Historical content: Exa Snapshot (snapshotAsOf on search and contents)
• SDK guidance: Python exa-py, TypeScript exa-js

Note on data retention: /search, /contents, /answer, and /agent offer Zero Data Retention (ZDR). Websets and the Monitors API (/monitors) are not ZDR. If a use case requires ZDR, stay on the ZDR surfaces or contact Exa.

Installation

# Python
pip install exa-py

# TypeScript / JavaScript
npm install exa-js

Install the latest SDK release with the package manager so it resolves the latest release and all SDK surfaces will be available.

Authentication

export EXA_API_KEY="your_api_key_here"

Exa accepts either the x-api-key header or Authorization: Bearer <key>.

The recommended Exa search request is the query plus token-efficient content extraction, and nothing else. Content extraction is a recommendation, not a server default: omit contents and results carry only metadata (title, URL, dates), no page content.

{
  "query": "latest developments in LLMs",
  "type": "auto",
  "contents": { "highlights": true }
}

Every other request field except objective is gated: add it only when the user's task explicitly requires it. Do not restate server defaults, and do not add controls because they seem plausibly useful. In particular:

• type defaults to auto; stating type: "auto" explicitly is fine, but do not send another mode unless the task requires it (for example a latency-critical UX or deep synthesis).
• numResults defaults to 10; omit numResults unless the task requires a different number of results. Set it only as an intentional product decision, not as boilerplate.
• Omit category. Use it only when the user explicitly asks for category-constrained retrieval.
• includeDomains and excludeDomains should be set only when the user explicitly requests a hard allowlist or blocklist and supplies or approves its contents. Express source preferences through query phrasing or systemPrompt instead.
• maxAgeHours should be set only when extracted page content must be current. It caps cache age before a live crawl; it is not a publication-recency filter.
• For "recent stories" tasks, put the recency in the query ("latest", "recent"). startPublishedDate / endPublishedDate are hard filters that drop undated and misdated pages; add them only when the task states a bounded window that must be enforced ("from the last seven days", "published in 2026"). Do not reach for maxAgeHours.
• highlights should be set to true by default for all tasks unless otherwise specified. Do not add maxCharacters or other highlight options without an explicit budget requirement in the task.
• objective belongs on every search that is one step of a larger task, such as a search an LLM agent calls as a tool, a query a model writes, or one step of a multi-step pipeline. Set it to the goal that search serves. Say which documents should rank first, which to exclude, and which facts or figures to pull. When an LLM calls search as a tool, the model writes objective alongside query. See Search as an LLM Tool.