Exa Search

Exa Search

Requires API key: Get one at https://dashboard.exa.ai/api-keys

Header: x-api-key: $EXA_API_KEY

Use POST https://api.exa.ai/search for semantic web retrieval, ranked results, and optional result-level extraction in one raw HTTP call. Start with type: "auto" for general retrieval. Add contents only when the caller needs page text, highlights, summaries, freshness-controlled crawling, subpages, or extracted links.

Quick Start (cURL)

Basic search

bashCopy code
curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "numResults": 10
  }'

Search with highlights

bashCopy code
curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "numResults": 5,
    "contents": {
      "highlights": true
    }
  }'

With filters and freshness

bashCopy code
curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "AI regulation policy updates",
    "type": "auto",
    "category": "news",
    "numResults": 10,
    "includeDomains": ["reuters.com", "bbc.com"],
    "startPublishedDate": "2025-01-01",
    "contents": {
      "text": {
        "maxCharacters": 2000
      },
      "maxAgeHours": 24,
      "livecrawlTimeout": 12000
    }
  }'

Deep search

bashCopy code
curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "map the major technical and commercial tradeoffs in sodium-ion batteries for grid storage",
    "type": "deep",
    "numResults": 8
  }'

Endpoint

textCopy code
POST https://api.exa.ai/search

Authentication: x-api-key: <API_KEY> header. Exa also accepts Authorization: Bearer <API_KEY>, but prefer x-api-key in cURL examples for consistency.

Use this endpoint when the agent needs search results. If the agent already has URLs and only needs extraction, use POST /contents instead.

Parameters

Core request parameters

Content parameters nested under contents

On /search, text, highlights, and summary must be nested under contents.

Text object options

Highlights object options

Prefer contents.highlights: true for the highest-quality default. Only use object form when the agent needs a custom focus or budget.

Summary object options

Search Types

Search type controls the retrieval and synthesis mode. Pick the mode for the workflow, not just the output format. Use auto or a deep variant for outputSchema, not lite. Use deeper modes when the search process itself needs more planning, synthesis, or reasoning.

With type: "lite", supported parameters are query (a single string), objective, userIdentifier, metadata, category, numResults, contents.highlights, contents.text, contents.snapshotAsOf, userLocation, includeDomains, excludeDomains, startPublishedDate, endPublishedDate, moderation, and compliance. Other documented search parameters are rejected, including outputSchema, systemPrompt, stream, and freshness options such as contents.maxAgeHours. Lite serves cached content without fetching pages at query time.

Use auto unless latency or reasoning depth is the primary constraint. Use lite for time-sensitive or cost-sensitive calls. Use deep, deep-lite, or deep-reasoning when the query needs multi-step source discovery, comparison, or synthesis.

Mode-only examples

jsonCopy code
{
  "query": "recent product launches from major AI chip companies",
  "type": "lite",
  "numResults": 5
}

jsonCopy code
{
  "query": "compare competing explanations for the recent rise in grid-scale battery deployments",
  "type": "deep",
  "numResults": 8
}

Structured Output

Use systemPrompt for behavior and outputSchema for shape. Keep the schema compact: a handful of named fields, shallow nesting, arrays that declare items. The example below is about as wide as /search wants. If you need more columns, drop the least important ones rather than grow the schema.

bashCopy code
curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "compare the latest frontier AI model releases",
    "type": "deep",
    "systemPrompt": "Prefer official sources and avoid duplicate results.",
    "outputSchema": {
      "type": "object",
      "properties": {
        "models": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "notable_claims": {
                "type": "array",
                "items": { "type": "string" }
              }
            },
            "required": ["name", "notable_claims"]
          }
        }
      },
      "required": ["models"]
    },
    "contents": {
      "highlights": true
    }
  }'

Keep schemas compact and bounded. Do not add citation fields to the schema; grounding is returned separately in output.grounding.

Streaming

Streaming applies to synthesized output, so include outputSchema along with -N, Accept: text/event-stream, and stream: true. Without outputSchema, the endpoint returns the normal JSON search response even when stream is true.

bashCopy code
curl -sS -N -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "recent grid-scale battery deployments",
    "type": "deep",
    "stream": true,
    "outputSchema": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      },
      "required": ["summary"]
    },
    "contents": {
      "highlights": true
    }
  }'

Treat streaming as SSE rather than JSON. Each data: frame contains an OpenAI-compatible chat completion chunk; read partial text from choices[0].delta.content and handle completion or error frames defensively.

Response Fields

Critical Pitfalls

• Keep text, highlights, and summary inside contents on /search.
• Do not send top-level text, highlights, or summary; that shape belongs to /contents.
• Do not send tokensNum; use contents.text.maxCharacters to cap extracted text.
• Do not use useAutoprompt, numSentences, or highlightsPerUrl in new requests.
• Use contents.maxAgeHours instead of livecrawl.
• Use documented categories only: company, people, research paper, news, personal site, and financial report.
• Avoid invalid category/filter combinations. company and people do not support startPublishedDate or endPublishedDate. company supports excludeDomains; people does not, and people only accepts LinkedIn domains in includeDomains.
• Pick one of contents.highlights, contents.text, or contents.summary by default. Stack modes only when the caller truly needs multiple views of each page.
• Expect SSE only when stream: true is paired with outputSchema; otherwise /search returns its normal JSON response.