pi-exa-search-api

Exa for pi across seven tools: search, contents, find similar, answer, code context, agent runs, and scheduled monitors. Structured output with field-level citations and confidence, plus multi-key rotation and custom TUI rendering.

pi install npm:pi-exa-search-api

Published on npm, which is what makes it discoverable in the pi package catalog. Or install from source:

pi install git:github.com/william-wei-zhu/pi-exa-search-api

Setup

pi-exa-search-api requires an Exa API key. Get one at dashboard.exa.ai/api-keys. New accounts include $20 of credits (roughly 2,800 searches), and the free tier adds $10 every month.

Then either:

export EXA_API_KEY="your-key"

or run /exa inside pi to add keys interactively. Keys are stored at ~/.pi/exa-config.json with 0600 permissions and are never written to logs, errors, or the transcript. Only the last four characters are ever displayed.

Add more than one key and pi-exa-search-api will rotate between them automatically.

Tools

Tool	Endpoint	Use for	Indicative price
exa_search	POST /search	Discovering pages: docs, news, facts, companies, people	$7 / 1k base; deep-lite/deep $12 / 1k; deep-reasoning $15 / 1k
exa_fetch	POST /contents	Reading full content for known URLs	$1 / 1k pages per content type (text + highlights bills 2×)
exa_similar	POST /findSimilar	Finding pages like a known good one†	See current Exa pricing
exa_answer	POST /answer	A short answer with citations	$5 / 1k
exa_code	POST /context	Real code examples and correct API syntax	~$1 / 1k
exa_agent	POST /agent/runs	Multi-hop research, list building, enrichment	$0.012-$1.00 / run
exa_monitors	/monitors	Scheduled recurring searches with semantic dedup	$15 / 1k runs

Contents requested with search are free for the first 10 results. Prices change: see Exa's current pricing. Exa returns actual costDollars with each supported response, and pi-exa-search-api exposes it as costUsd in tool details.

† Exa has deprecated findSimilar in exa-js with no announced replacement. The endpoint is still live, so exa_similar remains available, but it may be removed in a future API version.

exa_agent and exa_monitors are metered per run and are gated behind /exa-advanced.

Commands

Command	Description
/exa	Interactive key manager: add, reorder, test, remove
/exa-status	Keys available, tools active, cooldown state
/exa-enable	Enable all Exa tools
/exa-disable	Disable all Exa tools
/exa-advanced on|off	Toggle the metered tools (exa_agent, exa_monitors)

Usage

Search

Search for recent benchmarks comparing vector databases for RAG workloads.

Code, before writing code

Use exa_code to get the correct syntax for streaming with tool calls in the Vercel AI SDK.

Deep research in one call. deep-reasoning replaced Exa's retired /research endpoint:

Use exa_search with type="deep-reasoning" to compare Bun 2.0 and Deno 2.0 for production API servers.

Structured output with citations. Works on every search type, not just the deep ones:

Find the 5 largest AI infrastructure Series B rounds this year. Use outputSchema so I get
JSON with company, amount, and date.

Results come back with output.grounding: a citation list and a low/medium/high confidence label per field, rendered inline so you can see which values are actually supported.

Agent for list building

Use exa_agent with effort="low" and maxCostDollars=2 to find engineering leaders at AI
infra companies that raised a Series A in the last 6 months.

Search types

Type	Latency	Price	Best for
instant	~250 ms	$7 / 1k	Real-time apps, autocomplete
fast	~450 ms	$7 / 1k	Low latency with good relevance
auto	~1 s	$7 / 1k	Default; right for almost everything
deep-lite	~4 s	$12 / 1k	Lightweight synthesis
deep	4-15 s	$12 / 1k	Multi-step reasoning with structured output
deep-reasoning	12-40 s	$15 / 1k	Hardest research tasks

Key rotation

Every request goes through one chokepoint that rotates across configured keys and applies a cooldown per failure mode. Cooldowns are held in memory only and never persisted.

Response	Action	Cooldown
429	Next key	Retry-After if present (capped at 5 min), else 60s
401 / 403	Next key	60 min, likely an invalid key
402	Next key	10 min, out of credits
5xx / 408 / 425	Retry same key at 300ms, 900ms, then next key	n/a
Other 4xx	Fail immediately, no rotation	n/a

A malformed request fails identically on every key, so pi-exa-search-api does not burn the rest of your keys proving it.

Architecture

extensions/
├── index.ts        # registration, commands, tool gating, session lifecycle
├── api.ts          # single HTTP chokepoint: rotation, backoff, truncation, formatting
├── keys.ts         # key store (0600), cooldown ledger, timeouts
├── config.ts       # persisted UI state
├── key-manager.ts  # /exa TUI
└── tools/
    ├── search.ts   ├── fetch.ts    ├── similar.ts   ├── answer.ts
    ├── code.ts     ├── agent.ts    └── monitors.ts

Output is capped at ~45KB with the overflow written to a temp file, so a large crawl cannot blow out the context window.

Why not exa-js?

pi-exa-search-api calls the API over raw fetch rather than the official SDK. The rotation layer needs direct access to Retry-After headers, per-key AbortSignal composition, and raw response bodies, none of which a single-key SDK instance exposes cleanly. The tradeoff is deliberate; if you only need one key, exa-js is the better choice.

Development

npm install
npm run typecheck    # tsc --noEmit
npm test             # mocked unit tests, no API key needed
npm run check        # both

PI_EXA_LIVE=1 npm run test:live   # live smoke test, costs ~$0.05

The mocked suite (62 tests) covers the full rotation matrix (429 with and without Retry-After, 401, 402, 5xx backoff, key exhaustion, cooldown skipping, abort, malformed JSON), the parsing and grounding helpers, extension registration, and the published tarball (that files ships every runtime source, and that the catalog metadata is intact). The live suite hits every endpoint once and asserts the real response shapes. Both run in CI on Node 20 and 22.

Contributions welcome: see CONTRIBUTING.md.

License

MIT