---
name: exa-deep-search
description: Wrap Exa Deep Search API calls in a reusable CLI so agents can request auto, instant, deep, or reasoning searches without re-implementing the HTTP boilerplate.
compatibility: Created for Zo Computer
metadata:
  author: rob.zo.computer
---

# Overview
Use this skill as the single entry point for calling `https://api.exa.ai/search` so agents can focus on prompts, schema definitions, and grounding rather than HTTP details. `scripts/search.py` builds the payload, handles `x-api-key` from `EXA_API_KEY`, posts to the endpoint, and prints both the raw response and a short summary of the first `results` plus any `output.grounding` citations.

# Setup
1. Store your Exa API key as `EXA_API_KEY` in [Settings > Advanced](/?t=settings&s=advanced).
2. Review the official API reference for supported search types, categories, contents controls, and schema syntax: https://exa.ai/docs/reference/search-api-guide-for-coding-agents.

# Usage
```
python scripts/search.py \
  --query "latest filings from AI companies" \
  --type deep \
  --num-results 6 \
  --contents '{"highlights": {"maxCharacters": 4000}, "maxAgeHours": 0}' \
  --system-prompt "Focus on executive leadership changes" \
  --output-schema-file schema.json
```
- `--query` (required) is the natural-language search.
- `--type` chooses among `auto`, `fast`, `instant`, `deep`, or `deep-reasoning`.
- `--contents` accepts a JSON string for `contents` (highlights, summaries, crawl controls, etc.).
- `--category`, `--include-domains`, `--exclude-domains` scope results.
- `--system-prompt` guides the deep reasoning agent.
- `--output-schema-file` loads a JSON schema so Exa returns structured data (deep types only).
- `--extra params.json` merges additional top-level fields (`additionalQueries`, `dateRange`, `userLocation`, etc.).
- `--dry-run` prints the assembled payload without calling the API.

Set `EXA_SEARCH_DEFAULT_TYPE` and `EXA_SEARCH_DEFAULT_NUM_RESULTS` as environment variables for repeated runs so you can omit those flags.

# Common scenarios
1. **Company intelligence**: `--category company`, `--contents '{"highlights": {"maxCharacters": 3000}}'`, and a schema such as `{"companies": [{"name": "", "ceo_name": "", "hq": "", "funding_stage": ""}]}`. Use the `output.grounding` field for citations in follow-up reasoning.
2. **News sweeps**: `--type instant --num-results 5 --contents '{"highlights": {"maxCharacters": 2000}, "maxAgeHours": 0}'` for always-fresh coverage.
3. **Structured research**: `--type deep --system-prompt "Break the topic into sub-questions" --output-schema-file schema.json` to receive multi-source answers ready for downstream evaluation.

# Extending scenarios
- Store reusable payload fragments (e.g., `scenarios/company-update.json`) and pass them via `--extra scenarios/company-update.json` for consistent filters.
- If your agent needs a narrative explanation, add `"summary": {"query": "Explain in plain language."}` inside `--contents` so the response includes an LLM-written paragraph on top of the structured fields.
- Always parse `output.grounding` for URLs so your agent can trace every statement back to a source.