Exa agent search API

Primary sources: Homepage · Introducing Exa Agent (2026-06-16) · Agent guide · Search guide (coding agents) · Create a run · Search OpenAPI · Pricing · MCP · OpenAI SDK compat · llms.txt

Related vault: 2026-09-26 Cloud agent orchestrators in the wild · deep-research

Pin checked 2026-09-28 (Shanghai / UTC+8).

Product map

Positioning from docs/homepage: “A powerful web search tool designed for agents” / “web search built for AI agents” — index + retrieval + contents optimized for LLM context, not for human SERPs.

Surface	Endpoint(s)	Role
Search API	`POST https://api.exa.ai/search`	Natural-language search → ranked results + optional highlights/text/summary; optional `outputSchema` synthesis
Contents API	`POST /contents`	Same content options when you already have URLs (no search)
Deep Search	`/search` with `type` ∈ `deep-lite` / `deep` / `deep-reasoning`	Multi-step retrieve + synthesize on the Search path (seconds, not minutes)
Answer	`/answer` (also `/chat/completions` model `exa`)	LLM answer grounded on Exa search
Agent API	`POST /agent/runs` (+ get/list/cancel/stop/events)	Async context agent: fans out searches, reads, subagents, verification, Connect partners → one grounded structured result
Exa Connect	`dataSources` on Agent runs	Premium partner DBs (Fiber, Similarweb, Baselayer, …) inside the Agent loop
Monitors / Websets / Batch	separate APIs	Recurring search; verified datasets; async request batches — out of scope for this digest beyond naming

Auth (all products): Authorization: Bearer $EXA_API_KEY or x-api-key: $EXA_API_KEY. Keys: dashboard.exa.ai/api-keys. OpenAPI source of truth: exa-spec.yaml.

SDKs: pip install exa-py · npm install exa-js (exa-labs/exa-py, exa-labs/exa-js).

Enterprise claims on homepage (sourced): SOC 2 Type II, GDPR, CCPA, HIPAA (BAA available), Zero Data Retention (“queries and results are never stored or trained on” — ZDR is Enterprise, per-team; product matrix differs — see Gotchas).

Search API

POST https://api.exa.ai/search
Authorization: Bearer $EXA_API_KEY
Content-Type: application/json

Required: query (natural language). Default returns up to 10 results; numResults 1–100 (no pagination). No search without a query.

`type` (latency / depth)

From Search guide + OpenAPI + Pricing:

`type`	Typical latency	Base price (≤10 results)	Use when
`auto` (default)	~1 s	$7 / 1k	Default balance
`fast`	~450 ms	$7 / 1k	Latency-sensitive UI
`instant`	~250 ms	$7 / 1k	Real-time (chat/voice/autocomplete)
`deep-lite`	~4 s	$12 / 1k	Lightweight research + synthesis
`deep`	4–15 s	$12 / 1k	Multi-step + structured outputs
`deep-reasoning`	12–40 s	$15 / 1k	Max reasoning on Search path

Docs explicitly say: for long-running research / list building / multi-hop enrichment, prefer Exa Agent over deep-reasoning.

Additional results above 10: $1 / 1k results**. AI page summaries: **$ 1 / 1k pages.

Key knobs

Param	Notes
`numResults`	1–100; default 10
`category`	`company`, `publication`, `news`, `personal site`, `financial report`, `people` (+ string hints). `company` / `people` do not support `startPublishedDate`, `endPublishedDate`, `excludeDomains` (400 if used)
`includeDomains` / `excludeDomains`	Host, path prefix (`anthropic.com/news`), or `*.substack.com`. Prefer filters over `site:` in query. Max 1200 entries each
`startPublishedDate` / `endPublishedDate`	ISO 8601 publication window (hard filter)
`userLocation`	ISO country code (e.g. `US`)
`contents`	Nested: `highlights`, `text`, `summary`, `maxAgeHours`, `subpages`, `snapshotAsOf`, extras…
`outputSchema`	Root `type: "text"` or `"object"` → response `output.content` + `output.grounding`. Object schemas: ≤2 nesting levels, ≤10 properties. Adds ~2 s synthesis latency. Works with every `type`
`systemPrompt`	Behavior / source prefs for synthesis (not the response shape)
`stream`	SSE only when `outputSchema` is set; else normal JSON
`additionalQueries`	Deep-search variants only (1–10); expands research queries

Contents shapes

Recommended default: contents: { "highlights": true } — query-relevant excerpts, token-efficient.

highlights — excerpts sized to relevance (recommended for agents).
text — clean page body; often { "maxCharacters": N }.
summary — LLM summary per result (extra $ per page).

Pick one content view unless you need both — each view is billed separately. /search nests options under contents; /contents puts the same fields at top level next to urls.

Freshness (contents.maxAgeHours): omit = cache-with-fallback; positive = max cache age then refetch; 0 = always live fetch; -1 = cache only. This is content freshness, not publication-date filtering. Max 720 hours. Prefer this over deprecated livecrawl.

Minimal example

curl -s -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EXA_API_KEY" \
  -d '{
    "query": "recent techniques for improving retrieval in RAG systems",
    "type": "auto",
    "contents": { "highlights": true }
  }'

Exa Agent API

Introduced 2026-06-16: single API for frontier web research at lower cost via model fusion + Exa highlights (blog claims up to 94% token reduction from highlights). Strengths: deep research, list-building, entity enrichment; can split large jobs into parallel subagents.

Lifecycle

POST /agent/runs          → create (returns immediately unless SSE)
GET  /agent/runs/{id}     → poll
GET  /agent/runs          → list
POST …/cancel | …/stop    → cancel / graceful stop
GET  /agent/runs/{id}/events  → replay (non-ZDR); SSE with Accept

Statuses: queued → running → completed | failed | cancelled.

Create with Accept: text/event-stream (or SDK stream: true) for SSE: agent_run.created / .started / .completed / .failed / .cancelled. Treat live agent_run.source.added as preview; authoritative citations are terminal output.grounding.

Completed output:

output.text — prose
output.structured — JSON when outputSchema set
output.grounding — field-level citations (+ confidence)
usage / costDollars — ACUs, searches, emails, phones, Connect

Create request knobs

Field	Role
`query`	Required. Task spec: entity, count, criteria, evidence bar
`systemPrompt`	Extra behavior / judging rules
`effort`	`minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `auto` (default) \| `ultra`
`outputSchema`	JSON Schema → `output.structured` (draft-07 / 2019-09 / 2020-12 via `$schema`)
`input.data`	Rows/entities to enrich
`input.exclusion`	Records/entities to skip
`previousRunId`	Continue from a completed prior run (new ID each time)
`dataSources`	Up to 5 Connect providers (`fiber`, `similarweb`, `baselayer`, `affiliate`, `particle`, `jinko`, `polymarket`, `macrobond`, `financial_datasets`)
`budget.maxCostDollars`	Cap for `auto`/`ultra` only ( $1–$ 100; defaults $5 /$ 20)
`budget.maxDurationSeconds`	Soft wall-clock for `ultra` only (300–10800); `stopReason: time_limit_reached`
`metadata`	Caller key-value strings

stopReason examples: schema_satisfied, budget_reached, time_limit_reached, stopped, error, cancelled.

Effort / pricing (Agent)

From blog + Agent guide + Pricing — numbers match as of pin date:

Effort	Price	Best for
`minimal`	$0.012 / request	Lowest-cost lookups, short answers
`low`	$0.025 / request	Simple lookups, narrow facts
`medium`	$0.10 / request	Default starting point for standard research
`high`	$0.50 / request	Harder research, more citations
`xhigh`	$1.00 / request	Completeness ≫ cost/latency (fixed)
`auto`	Metered; default cap $5	Variable scope / list building
`ultra`	Metered; default cap $20	Large lists, exhaustive research

Metered usage rates (also apply under auto/ultra caps):

Component	Price
Agent Compute Unit (ACU)	$0.10 / ACU
Search tool call	$0.005 / search
Email enrichment	$0.02 / email
Phone enrichment	$0.07 / phone

Connect is additive (examples from Connect overview: Fiber $0.02/credit, Similarweb$ 0.30/credit, Baselayer $0.10–$ 4.00/order, etc.).

Free tier (Search/etc.): ** $10** credits on signup, resets to$ 10 monthly; + one-time $10 onboarding bonus (Pricing).

OpenAI-compatible Responses API

Still accurate per OpenAI SDK Compatibility:

base_url = https://api.exa.ai
model    = "exa-agent"     # → Agent API
           "exa"           # → /answer via /chat/completions

Mode	How	Behavior
Sync	default	Blocks until complete
Stream	`stream: true`	OpenAI Responses SSE → `response.completed`
Background	`background: true`	Immediate `in_progress`; poll `GET /responses/{id}`

Map effort via reasoning.effort (same enum). high / xhigh / ultra cannot be synchronous (400) — use stream or background. No budget field on /responses; ultra uses default cap. Continue with previous_response_id. Cancel: POST /responses/{id}/cancel.

Create example

curl -s -X POST "https://api.exa.ai/agent/runs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EXA_API_KEY" \
  -d '{
    "query": "Find engineering leaders at AI infrastructure companies that raised a Series A or B in the last 6 months.",
    "effort": "auto",
    "outputSchema": {
      "type": "object",
      "required": ["people"],
      "properties": {
        "people": {
          "type": "array",
          "maxItems": 10,
          "items": {
            "type": "object",
            "required": ["name", "job_title", "linkedin_url"],
            "properties": {
              "name": { "type": "string" },
              "job_title": { "type": "string" },
              "linkedin_url": { "type": "string", "format": "uri" }
            }
          }
        }
      }
    }
  }'

MCP / coding agents / Connect

Hosted MCP

URL: https://mcp.exa.ai/mcp (docs, exa-labs/exa-mcp-server).

Tool	Default	Purpose
`web_search_exa`	on	Ordinary web search + ready content
`web_fetch_exa`	on	Contents for known URLs
`web_search_advanced_exa`	opt-in	Filters, dates, highlights, freshness, subpages
`agent_run`	on with OAuth/API key	Multi-step Agent (not on free keyless limits)

Auth modes: keyless (rate-limited), OAuth (?login), API key (x-api-key). Cursor example: { "mcpServers": { "exa": { "url": "https://mcp.exa.ai/mcp" } } }. Local: npx -y exa-mcp-server with EXA_API_KEY.

agent_run long jobs: tool may return status: "running" + id; client re-calls with runId. Follow-ups on completed work use previousRunId (not the same as waiting on runId).

Agent skills

npx skills add exa-labs/agent-skills

Repo: exa-labs/agent-skills — build-with-exa, exa-search, exa-contents, company-research, lead-generation. Also installable as Exa plugin in ChatGPT/Codex, Claude (claude plugin install exa@claude-plugins-official), Grok Build marketplace.

Exa Connect

Attach partners on Agent runs via dataSources: [{ "provider": "…" }]. Agent picks partner tools when outputSchema field descriptions name the source (e.g. “from Similarweb”). Index search remains available on every run; Connect is premium overlay. Unavailable under ZDR (400 if requested).

When to use which

Need	Start with
Ranked pages + highlights for your LLM / tool loop	Search `auto` / `fast` / `instant`
One-shot synthesis / small structured JSON in seconds	Deep Search (`deep-lite` / `deep`) + `outputSchema`
Known URLs only	Contents
Async list building, multi-hop, enrichment over rows, verification	Agent
Premium B2B / traffic / KYB / markets data fused with web	Agent + Connect
Coding agent in Cursor/Claude/Codex without custom HTTP	MCP (`web_search_exa` / `agent_run`)

Rule of thumb from Agent best practices: Search when you need pages quickly and your app does the reasoning; Agent when the product would otherwise be a loop of search → read → verify → enrich.

Gotchas

Search

Put content options under contents on /search (not top-level text/highlights).
Do not copy legacy params: useAutoprompt, includeUrls/excludeUrls, livecrawl, crawl-date filters, includeText/excludeText, context — see Search best practices → Common mistakes.
maxAgeHours ≠ publication date; use date filters for “newer articles,” freshness for “live page content.”
company/people categories: unsupported filters → 400.
Combining highlights+text+summary bills each view.
Python SDK: snake_case everywhere (max_age_hours, output_schema, …).
Search outputSchema object limits: 2 levels / 10 properties; citations live in output.grounding, not your schema.
Prefer Agent over stacking deep-reasoning for list-building.

Agent

Create response ≠ final answer — persist id, poll or stream.
Schema adherence validates shape, not truth; fields may be null despite required; stopReason: schema_satisfied allows nulls.
Bound arrays with maxItems for cost predictability (esp. contact formats email / phone).
Keep rows in input.data, exclusions in input.exclusion, shape in outputSchema — don’t paste tables into query.
Verification schemas should include uncertainty enums (cannot_verify vs absent).
Fixed efforts = predictable $; `auto`/`ultra` without `budget.maxCostDollars` can run to$ 5/$20 defaults.
Event replay / previousRunId / Connect blocked under ZDR.

ZDR / compliance (ZDR docs)

Product	ZDR
Search, Contents, Agent	Available (Enterprise, per team)
Answer, Websets	Not currently supported

Agent ZDR: stream or poll within ~10 minutes after terminal status; then irretrievable. Homepage “never stored” marketing applies in the ZDR/Enterprise framing — enable via sales (sales@exa.ai), don’t assume default.

MCP

Explicit ?tools= replaces defaults — include every tool you want.
agent_run needs OAuth or API key (not keyless).

Sources

Gaps / not verified live

Did not call the live API (no key exercised); pricing copied from official Pricing + Agent guide + Jun 2026 blog — all three agreed on fixed effort $.
Rate limits / concurrency numbers deferred to Billing / Agent limits (not fully pulled).
Full Connect per-operation price tables only sampled from overview; Fiber/Similarweb credit math is deeper in partner pages.
Absolute Search guide URL …/search-api-guide also exists; coding-agents guide was the requested primary and is current.
No screenshots embedded (API/reference tables suffice; Attachments unused).

Exa agent search API

Exa agent search API

Product map

Search API

type (latency / depth)

Key knobs

Contents shapes

Minimal example

Exa Agent API

Lifecycle

Create request knobs

Effort / pricing (Agent)

OpenAI-compatible Responses API

Create example

MCP / coding agents / Connect

Hosted MCP

Agent skills

Exa Connect

When to use which

Gotchas

Sources

Gaps / not verified live

`type` (latency / depth)