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