Searching with Exa (Search API)
This skill is a recipe for consistent web research using Exa’s Search API: you choose the right search mode, apply the right filters, request only the content you need (highlights/text/summary), and return clean citations.
Quick start (default path)
- Ensure an API key is available as an environment variable:
EXA_API_KEY (preferred)
- or pass
--api-key to the scripts.
- Run a search (JSON response to stdout):
python {baseDir}/scripts/exa_search.py --query "latest research in LLMs" --type auto --category "research paper" --num-results 5 --highlights --highlights-per-url 3 --num-sentences 2
Operating principles (always follow)
- Always return URLs. Prefer also returning title + a 1–2 sentence “why this source” note.
- Prefer
highlights first for agentic workflows. Escalate to full text only when necessary.
- Use filters aggressively: domain allowlists, date windows, and
category improve relevance and reduce noise.
- Freshness is explicit: if the user asks for “latest”, “today”, “current”, etc., set a freshness policy (see below).
- Don’t overfetch: cap content length with
maxCharacters when requesting text.
- If the user needs hard evidence (numbers, quotes), fetch full text for the top 1–3 pages and verify.
Workflow
Step 1 — Translate the user task into a search plan
Decide:
Search type
auto (default): best general quality.
instant: lowest latency, for autocomplete / live suggestions.
deep: more comprehensive; can use additionalQueries.
fast / neural: streamlined alternatives.
Category (when appropriate)
news, research paper, company, people, tweet, personal site, financial report, etc.
Freshness
- If “real-time / latest”: consider live crawling via
maxAgeHours (see Freshness).
- If “historical/static”: use cache only (e.g.,
maxAgeHours: -1).
Content mode
highlights: token-efficient evidence snippets.
text: deep reading (cap via maxCharacters).
summary: quick structured overviews (optionally with a guiding query).
Step 2 — Build the request payload
Start from this template and fill only what you need:
{
"query": "...",
"type": "auto",
"category": "news",
"numResults": 10,
"includeDomains": ["..."],
"excludeDomains": ["..."],
"startPublishedDate": "2025-01-01T00:00:00.000Z",
"endPublishedDate": "2025-12-31T23:59:59.999Z",
"includeText": ["must contain phrase"],
"excludeText": ["must not contain phrase"],
"contents": {
"highlights": true,
"text": { "maxCharacters": 8000, "includeHtmlTags": false },
"summary": { "query": "..." },
"subpages": 0,
"extras": { "links": 0, "imageLinks": 0 },
"maxAgeHours": 24
}
}
Notes:
contents is optional. If omitted, you’ll only get metadata (title, url, etc.).
maxAgeHours controls when Exa should live-crawl vs use cached content (see below).
context is deprecated; use highlights or text instead.
Step 3 — Execute the request
Option A (recommended): use the bundled script so requests are consistent and validated.
python {baseDir}/scripts/exa_search.py --query "..." --highlights --num-results 10
Option B: call the HTTP endpoint directly.
curl --request POST --url https://api.exa.ai/search --header "content-type: application/json" --header "x-api-key: $EXA_API_KEY" --data '{"query":"...","type":"auto","numResults":5}'
Step 4 — Post-process results into an answer with citations
- De-duplicate near-identical domains/pages when the user wants breadth.
- Select the top sources (usually 3–7) that jointly cover the claim space.
- For each selected result, extract:
- title, url
- key highlight(s) or a short quote from
text
- published date (if available)
- Write the response with inline citations (URLs) and clear uncertainty where needed.
- If the user wants a deliverable (report, memo), preserve a “Sources” section listing all URLs.
Freshness policy (use this when “latest/current/today” appears)
Use contents.maxAgeHours (or the maxAgeHours top-level alias if the API accepts it):
24: daily-fresh content (use cache if <24h else livecrawl)
1: near-real-time (cache if <1h else livecrawl)
0: always livecrawl (slowest, most current)
-1: never livecrawl (fastest; cache only)
- omit: default behaviour (livecrawl only when cache missing)
Common patterns
Pattern A — “Give me sources for X” (fast + token efficient)
type: auto, numResults: 5–10
contents.highlights: true
- Optional:
category and includeDomains
Pattern B — “Do deep research on X” (read a few pages thoroughly)
- Start with highlights on 10–20 results.
- Then fetch full
text for the top 3–5 URLs with a maxCharacters cap.
- Summarise with citations.
Pattern C — “Latest news about X”
category: news
- Apply a date window (
startPublishedDate) if the question is time-bound.
- Use a freshness setting (often
maxAgeHours: 1–24).
Pattern D — “Find a company / person page”
category: company or people
- If using
people, allowlist LinkedIn domains when needed.
- IMPORTANT: some filters are unsupported for
company/people; see troubleshooting.
Troubleshooting
401 / 403 (auth)
- Confirm
x-api-key header is present and valid.
- Confirm you aren’t accidentally using a placeholder like
YOUR-EXA-API-KEY.
400 (invalid parameters)
company and people categories support a limited set of filters; unsupported parameters can trigger 400 errors.
- If in doubt, remove date and text filters first, then re-add one-by-one.
Too much content / token blow-ups
- Prefer
highlights over text.
- Cap
text.maxCharacters.
- Reduce
numResults.
Bundled references
- API + parameter cheat sheet:
references/exa-search-api.md
- Best-practice recipes:
references/exa-search-best-practices.md
- Quickstart snippets (SDK + curl):
references/exa-search-quickstart.md
1---
2name: exa-search
3description: >-
4 Searches the web via Exa’s Search API and returns source URLs (optionally with highlights, full text, summaries, and subpages).
5 Use when the user asks to “search with Exa”, “use Exa”, “find sources/URLs”, “do web research”, “retrieve webpage text”,
6 “get highlights/summaries”, “filter by domain/date/category”, or needs fresh results (news, real-time lookups).
7metadata:
8 source: https://skillmd.com/skills/tristanmanchester/exa-search
9 author: "generated-by-chatgpt"
10 version: "1.0.0"
11 upstream_docs:
12 - "https://exa.ai/docs/reference/search"
13 - "https://exa.ai/docs/reference/search-quickstart"
14 - "https://exa.ai/docs/reference/search-best-practices"
15---
16
17# Searching with Exa (Search API)
18
19This skill is a **recipe for consistent web research** using Exa’s Search API: you choose the right search mode, apply the right filters, request only the content you need (highlights/text/summary), and return clean citations.
20
21## Quick start (default path)
22
231) Ensure an API key is available as an environment variable:
24
25- `EXA_API_KEY` (preferred)
26- or pass `--api-key` to the scripts.
27
282) Run a search (JSON response to stdout):
29
30```bash
31python {baseDir}/scripts/exa_search.py --query "latest research in LLMs" --type auto --category "research paper" --num-results 5 --highlights --highlights-per-url 3 --num-sentences 2
32```
33
34## Operating principles (always follow)
35
36- **Always return URLs**. Prefer also returning title + a 1–2 sentence “why this source” note.
37- **Prefer `highlights` first** for agentic workflows. Escalate to full `text` only when necessary.
38- **Use filters aggressively**: domain allowlists, date windows, and `category` improve relevance and reduce noise.
39- **Freshness is explicit**: if the user asks for “latest”, “today”, “current”, etc., set a freshness policy (see below).
40- **Don’t overfetch**: cap content length with `maxCharacters` when requesting `text`.
41- **If the user needs hard evidence** (numbers, quotes), fetch full text for the top 1–3 pages and verify.
42
43## Workflow
44
45### Step 1 — Translate the user task into a search plan
46
47Decide:
48
491. **Search type**
50 - `auto` (default): best general quality.
51 - `instant`: lowest latency, for autocomplete / live suggestions.
52 - `deep`: more comprehensive; can use `additionalQueries`.
53 - `fast` / `neural`: streamlined alternatives.
54
552. **Category** (when appropriate)
56 - `news`, `research paper`, `company`, `people`, `tweet`, `personal site`, `financial report`, etc.
57
583. **Freshness**
59 - If “real-time / latest”: consider live crawling via `maxAgeHours` (see *Freshness*).
60 - If “historical/static”: use cache only (e.g., `maxAgeHours: -1`).
61
624. **Content mode**
63 - `highlights`: token-efficient evidence snippets.
64 - `text`: deep reading (cap via `maxCharacters`).
65 - `summary`: quick structured overviews (optionally with a guiding `query`).
66
67### Step 2 — Build the request payload
68
69Start from this template and fill only what you need:
70
71```json
72{
73 "query": "...",
74 "type": "auto",
75 "category": "news",
76 "numResults": 10,
77 "includeDomains": ["..."],
78 "excludeDomains": ["..."],
79 "startPublishedDate": "2025-01-01T00:00:00.000Z",
80 "endPublishedDate": "2025-12-31T23:59:59.999Z",
81 "includeText": ["must contain phrase"],
82 "excludeText": ["must not contain phrase"],
83 "contents": {
84 "highlights": true,
85 "text": { "maxCharacters": 8000, "includeHtmlTags": false },
86 "summary": { "query": "..." },
87 "subpages": 0,
88 "extras": { "links": 0, "imageLinks": 0 },
89 "maxAgeHours": 24
90 }
91}
92```
93
94Notes:
95- `contents` is optional. If omitted, you’ll only get metadata (`title`, `url`, etc.).
96- `maxAgeHours` controls when Exa should live-crawl vs use cached content (see below).
97- `context` is deprecated; use `highlights` or `text` instead.
98
99### Step 3 — Execute the request
100
101**Option A (recommended):** use the bundled script so requests are consistent and validated.
102
103```bash
104python {baseDir}/scripts/exa_search.py --query "..." --highlights --num-results 10
105```
106
107**Option B:** call the HTTP endpoint directly.
108
109```bash
110curl --request POST --url https://api.exa.ai/search --header "content-type: application/json" --header "x-api-key: $EXA_API_KEY" --data '{"query":"...","type":"auto","numResults":5}'
111```
112
113### Step 4 — Post-process results into an answer with citations
114
1151. **De-duplicate** near-identical domains/pages when the user wants breadth.
1162. **Select the top sources** (usually 3–7) that jointly cover the claim space.
1173. For each selected result, extract:
118 - title, url
119 - key highlight(s) or a short quote from `text`
120 - published date (if available)
1214. **Write the response** with inline citations (URLs) and clear uncertainty where needed.
1225. If the user wants a deliverable (report, memo), preserve a “Sources” section listing all URLs.
123
124## Freshness policy (use this when “latest/current/today” appears)
125
126Use `contents.maxAgeHours` (or the `maxAgeHours` top-level alias if the API accepts it):
127
128- `24`: daily-fresh content (use cache if <24h else livecrawl)
129- `1`: near-real-time (cache if <1h else livecrawl)
130- `0`: always livecrawl (slowest, most current)
131- `-1`: never livecrawl (fastest; cache only)
132- omit: default behaviour (livecrawl only when cache missing)
133
134## Common patterns
135
136### Pattern A — “Give me sources for X” (fast + token efficient)
137- `type: auto`, `numResults: 5–10`
138- `contents.highlights: true`
139- Optional: `category` and `includeDomains`
140
141### Pattern B — “Do deep research on X” (read a few pages thoroughly)
142- Start with highlights on 10–20 results.
143- Then fetch full `text` for the top 3–5 URLs with a `maxCharacters` cap.
144- Summarise with citations.
145
146### Pattern C — “Latest news about X”
147- `category: news`
148- Apply a date window (`startPublishedDate`) if the question is time-bound.
149- Use a freshness setting (often `maxAgeHours: 1–24`).
150
151### Pattern D — “Find a company / person page”
152- `category: company` or `people`
153- If using `people`, allowlist LinkedIn domains when needed.
154- IMPORTANT: some filters are unsupported for `company`/`people`; see troubleshooting.
155
156## Troubleshooting
157
158### 401 / 403 (auth)
159- Confirm `x-api-key` header is present and valid.
160- Confirm you aren’t accidentally using a placeholder like `YOUR-EXA-API-KEY`.
161
162### 400 (invalid parameters)
163- `company` and `people` categories support a limited set of filters; unsupported parameters can trigger 400 errors.
164- If in doubt, remove date and text filters first, then re-add one-by-one.
165
166### Too much content / token blow-ups
167- Prefer `highlights` over `text`.
168- Cap `text.maxCharacters`.
169- Reduce `numResults`.
170
171## Bundled references
172
173- API + parameter cheat sheet: `references/exa-search-api.md`
174- Best-practice recipes: `references/exa-search-best-practices.md`
175- Quickstart snippets (SDK + curl): `references/exa-search-quickstart.md`