Exa

Routing layer for Exa API work. WHAT/guardrails here; HOW in reference/endpoints.md and lib/exa.py. Full docs cached at reference/docs/exa/raw/llms-full.txt.

Auth & config

• Base URL: https://api.exa.ai
• Auth: header x-api-key (Exa → Dashboard → API Keys). Env EXA_API_KEY; never hardcode.
• No cursor pagination: search/find_similar return up to num_results (provider-capped); raise it or refine the query for more.

Operations

• search(query, type=, category=, num_results=, contents=) — neural/auto search. type: auto|neural|keyword|fast|deep. category: company | research paper | news | linkedin profile | etc. Pass contents={"text": True} to get page text in one call.
• get_contents(urls, text=, ...) — cleaned page text/highlights/summary for URLs.
• find_similar(url, num_results=) — expand from a seed URL (lookalike pages/companies).
• answer(query, text=) — cited LLM answer grounded in Exa results.
• Everything else (websets people/company search, monitors, chat/completions) → generic request(method, path, json=) + cached docs.

Cost note

Every search / get_contents / find_similar / answer call is charged, including one that matches nothing — Exa prices the request it accepted. The card price covers the base request; results beyond the first 10, a per-result summary, extra content types, more URLs, and a deep/deep-reasoning type each raise it. Keep num_results tight, ask only for the content types you will read, and prefer one search with contents over separate calls. Agent runs are charged when they complete (a failed/cancelled run is not charged; auto effort has no cap — set an explicit effort and bound outputSchema arrays with maxItems when spend must be predictable). No outreach side-effects — read-only research tool, so no send guardrails (just spend awareness).

Handoff

Use Exa for discovery + research in the recruiting funnel: find candidate/company pages and signals → pull text → hand structured findings to enrichment (Apollo/Lusha/etc.) or to an ATS write. Pairs with the rest of the sourcing pipeline.

Field notes (production experience)

Field-shape note: these are vendor-native operational notes. The client returns the raw vendor JSON and uses the method names in this file — read field shapes accordingly (no normalized-wrapper / result.data. prefix).

• type vs category are independent: type = search strategy (auto/fast/neural/deep); category = result-type filter (company/people/news/financial report). type:"news" is a 422 error - use category:"news".
• Order: run search/contents first and inspect citations; treat answer as the synthesis layer, not the first retrieval step, when precision matters.
• Use focused queries + small numResults on pilots, widen only if recall is low.

Callable surface — lib/exa.py

Import: from lib.exa import Exa → instantiate Exa() (reads key from env). Base: https://api.exa.ai. Generic passthrough: request(method, path, *, params, json).

• answer(query: str, *, text: bool = False, **opts) -> dict — POST /answer — LLM answer grounded in Exa search results, with citations.
• budget_remaining() -> dict — Remaining Exa balance — NOT callable by a workspace. It reads a Hyreflow-side Exa balance rather than the caller's own account, so connecting your own Exa key does not unlock it; the engine refuses it on the workspace path regardless of BYOK.
• find_similar(url: str, *, num_results: int = 10, **opts) -> dict — POST /findSimilar — find pages semantically similar to a seed URL.
• get_agent_run(run_id: str) -> dict — GET /agent/runs/{run_id} — fetch an Exa Agent run's status and result.
• get_contents(urls: list[str], *, text: bool = True, **opts) -> dict — POST /contents — fetch cleaned page content for URLs (text/highlights/summary).
• list_agent_runs(*, limit: int = 10, **opts) -> dict — GET /agent/runs — list recent Exa Agent runs (id/status/createdAt/request).
• ping() -> dict — BYOK key-verification probe. Exa's usage endpoint needs an api-key id in the path, so this fires the cheapest real search (1 result) to confirm the key authenticates — NOT free, ~1 search charge on the caller's own Exa account.
• search(query: str, *, num_results: int = 10, type: str | None = None, category: str | None = None, contents: dict | None = None, **opts) -> dict — POST /search — neural/auto web search. type: auto|neural|keyword|fast|deep.
• start_agent_run(query: str, *, output_schema: dict | None = None, effort: str | None = None, input: dict | None = None, data_sources: list | None = None, previous_run_id: str | None = None, **opts) -> dict — POST /agent/runs — start an async Exa Agent research/list-build run; returns a run id to poll.