exa-ai 0.13.0 → 0.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +119 -73
- data/exe/exa-ai +41 -136
- data/exe/exa-ai-agent-run-create +55 -20
- data/exe/exa-ai-agent-run-delete +1 -8
- data/exe/exa-ai-agent-run-events +21 -1
- data/exe/exa-ai-agent-run-list +1 -1
- data/exe/exa-ai-agent-run-stop +93 -0
- data/exe/exa-ai-answer +25 -0
- data/exe/exa-ai-context +6 -2
- data/exe/exa-ai-find-similar +26 -68
- data/exe/exa-ai-get-contents +138 -42
- data/exe/exa-ai-search +27 -104
- data/exe/exa-ai-search-monitor-batch +93 -0
- data/exe/exa-ai-search-monitor-create +104 -0
- data/exe/exa-ai-search-monitor-delete +69 -0
- data/exe/exa-ai-search-monitor-get +69 -0
- data/exe/exa-ai-search-monitor-list +73 -0
- data/exe/exa-ai-search-monitor-runs-get +68 -0
- data/exe/exa-ai-search-monitor-runs-list +75 -0
- data/exe/exa-ai-search-monitor-trigger +69 -0
- data/exe/exa-ai-search-monitor-update +102 -0
- data/lib/exa/cli/base.rb +57 -0
- data/lib/exa/cli/contents_flags.rb +199 -0
- data/lib/exa/cli/formatters/agent_run_formatter.rb +79 -3
- data/lib/exa/cli/formatters/search_formatter.rb +18 -2
- data/lib/exa/cli/formatters/search_monitor_formatter.rb +98 -0
- data/lib/exa/cli/search_parser.rb +46 -87
- data/lib/exa/client.rb +186 -310
- data/lib/exa/resources/agent_run.rb +5 -3
- data/lib/exa/resources/agent_run_deletion.rb +17 -0
- data/lib/exa/resources/answer.rb +3 -3
- data/lib/exa/resources/contents_result.rb +5 -1
- data/lib/exa/resources/find_similar_result.rb +5 -1
- data/lib/exa/resources/search_monitor.rb +42 -0
- data/lib/exa/resources/search_monitor_batch_result.rb +11 -0
- data/lib/exa/resources/search_monitor_list.rb +19 -0
- data/lib/exa/resources/search_monitor_run.rb +46 -0
- data/lib/exa/resources/search_monitor_trigger_result.rb +11 -0
- data/lib/exa/resources/search_result.rb +11 -1
- data/lib/exa/services/agent_run_cancel.rb +1 -12
- data/lib/exa/services/agent_run_create.rb +1 -12
- data/lib/exa/services/agent_run_delete.rb +6 -14
- data/lib/exa/services/agent_run_events.rb +33 -4
- data/lib/exa/services/agent_run_get.rb +1 -12
- data/lib/exa/services/agent_run_list.rb +1 -12
- data/lib/exa/services/agent_run_stop.rb +21 -0
- data/lib/exa/services/agent_run_stream.rb +53 -51
- data/lib/exa/services/answer.rb +5 -2
- data/lib/exa/services/answer_stream.rb +54 -45
- data/lib/exa/services/context.rb +3 -1
- data/lib/exa/services/find_similar.rb +9 -2
- data/lib/exa/services/get_contents.rb +14 -15
- data/lib/exa/services/parameter_converter.rb +128 -111
- data/lib/exa/services/search.rb +58 -19
- data/lib/exa/services/search_monitors/batch.rb +36 -0
- data/lib/exa/services/search_monitors/create.rb +37 -0
- data/lib/exa/services/search_monitors/delete.rb +22 -0
- data/lib/exa/services/search_monitors/get.rb +22 -0
- data/lib/exa/services/search_monitors/list.rb +29 -0
- data/lib/exa/services/search_monitors/runs_get.rb +23 -0
- data/lib/exa/services/search_monitors/runs_list.rb +29 -0
- data/lib/exa/services/search_monitors/trigger.rb +22 -0
- data/lib/exa/services/search_monitors/update.rb +42 -0
- data/lib/exa/services/search_stream.rb +38 -0
- data/lib/exa/version.rb +1 -1
- data/lib/exa.rb +18 -50
- metadata +30 -84
- data/exe/exa-ai-enrichment-cancel +0 -108
- data/exe/exa-ai-enrichment-create +0 -226
- data/exe/exa-ai-enrichment-delete +0 -122
- data/exe/exa-ai-enrichment-get +0 -104
- data/exe/exa-ai-enrichment-list +0 -99
- data/exe/exa-ai-enrichment-update +0 -171
- data/exe/exa-ai-import-create +0 -253
- data/exe/exa-ai-import-delete +0 -92
- data/exe/exa-ai-import-get +0 -92
- data/exe/exa-ai-import-list +0 -72
- data/exe/exa-ai-import-update +0 -164
- data/exe/exa-ai-monitor-create +0 -223
- data/exe/exa-ai-monitor-delete +0 -101
- data/exe/exa-ai-monitor-get +0 -92
- data/exe/exa-ai-monitor-list +0 -90
- data/exe/exa-ai-monitor-runs-get +0 -103
- data/exe/exa-ai-monitor-runs-list +0 -110
- data/exe/exa-ai-monitor-update +0 -207
- data/exe/exa-ai-webset-cancel +0 -97
- data/exe/exa-ai-webset-create +0 -254
- data/exe/exa-ai-webset-delete +0 -111
- data/exe/exa-ai-webset-get +0 -93
- data/exe/exa-ai-webset-item-delete +0 -111
- data/exe/exa-ai-webset-item-get +0 -105
- data/exe/exa-ai-webset-item-list +0 -108
- data/exe/exa-ai-webset-list +0 -91
- data/exe/exa-ai-webset-search-cancel +0 -104
- data/exe/exa-ai-webset-search-create +0 -247
- data/exe/exa-ai-webset-search-get +0 -105
- data/exe/exa-ai-webset-update +0 -143
- data/lib/exa/cli/formatters/enrichment_formatter.rb +0 -125
- data/lib/exa/cli/formatters/import_formatter.rb +0 -153
- data/lib/exa/cli/formatters/monitor_formatter.rb +0 -144
- data/lib/exa/cli/formatters/monitor_run_formatter.rb +0 -126
- data/lib/exa/cli/formatters/webset_formatter.rb +0 -134
- data/lib/exa/cli/formatters/webset_item_formatter.rb +0 -131
- data/lib/exa/cli/formatters/webset_search_formatter.rb +0 -57
- data/lib/exa/constants/websets.rb +0 -19
- data/lib/exa/resources/import.rb +0 -86
- data/lib/exa/resources/import_collection.rb +0 -33
- data/lib/exa/resources/monitor.rb +0 -48
- data/lib/exa/resources/monitor_collection.rb +0 -30
- data/lib/exa/resources/monitor_run.rb +0 -52
- data/lib/exa/resources/monitor_run_collection.rb +0 -30
- data/lib/exa/resources/webset.rb +0 -74
- data/lib/exa/resources/webset_collection.rb +0 -33
- data/lib/exa/resources/webset_enrichment.rb +0 -71
- data/lib/exa/resources/webset_enrichment_collection.rb +0 -28
- data/lib/exa/resources/webset_item_collection.rb +0 -33
- data/lib/exa/resources/webset_search.rb +0 -112
- data/lib/exa/services/websets/cancel.rb +0 -36
- data/lib/exa/services/websets/cancel_enrichment.rb +0 -35
- data/lib/exa/services/websets/cancel_search.rb +0 -44
- data/lib/exa/services/websets/create.rb +0 -45
- data/lib/exa/services/websets/create_enrichment.rb +0 -35
- data/lib/exa/services/websets/create_search.rb +0 -48
- data/lib/exa/services/websets/create_search_validator.rb +0 -128
- data/lib/exa/services/websets/create_validator.rb +0 -213
- data/lib/exa/services/websets/delete.rb +0 -36
- data/lib/exa/services/websets/delete_enrichment.rb +0 -35
- data/lib/exa/services/websets/delete_item.rb +0 -20
- data/lib/exa/services/websets/get_item.rb +0 -20
- data/lib/exa/services/websets/get_search.rb +0 -43
- data/lib/exa/services/websets/import_create.rb +0 -40
- data/lib/exa/services/websets/import_delete.rb +0 -37
- data/lib/exa/services/websets/import_get.rb +0 -37
- data/lib/exa/services/websets/import_list.rb +0 -25
- data/lib/exa/services/websets/import_update.rb +0 -38
- data/lib/exa/services/websets/import_upload.rb +0 -59
- data/lib/exa/services/websets/list.rb +0 -25
- data/lib/exa/services/websets/list_items.rb +0 -26
- data/lib/exa/services/websets/monitors/create.rb +0 -42
- data/lib/exa/services/websets/monitors/delete.rb +0 -32
- data/lib/exa/services/websets/monitors/get.rb +0 -33
- data/lib/exa/services/websets/monitors/list.rb +0 -27
- data/lib/exa/services/websets/monitors/runs/get.rb +0 -37
- data/lib/exa/services/websets/monitors/runs/list.rb +0 -30
- data/lib/exa/services/websets/monitors/update.rb +0 -33
- data/lib/exa/services/websets/retrieve.rb +0 -47
- data/lib/exa/services/websets/retrieve_enrichment.rb +0 -35
- data/lib/exa/services/websets/update.rb +0 -37
- data/lib/exa/services/websets/update_enrichment.rb +0 -36
- data/lib/exa/services/websets_parameter_converter.rb +0 -45
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 4aa92257e4c27dbbd7cd5db638d95d40e76c8d75a92209069a769f1404ace64f
|
|
4
|
+
data.tar.gz: 33b82648f530fd688751fd2f48808b332efc420fcf4f7fd8360f9a2fca476da1
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 4127f458266b07c9f6989eca0a5b8333d98775fa488692af84488ebacfb3104dd23b5eaa5f72f3ab9d606d7ea76746bcb15598d213dc8b7e2154ff6a74f288e7
|
|
7
|
+
data.tar.gz: e8ada14ef4109d77e7c2bbb7647520b441005e68fb4a16c491464877d13d6a80d904b318a6ed8cbe4563de3bfcefd3f26c0c2e85a5f20b6a6eb34bdea18a453b
|
data/README.md
CHANGED
|
@@ -10,6 +10,7 @@ Ruby client for the Exa.ai API. Search and analyze web content using neural sear
|
|
|
10
10
|
- [Quick Start](#quick-start)
|
|
11
11
|
- [Features](#features)
|
|
12
12
|
- [Agent](#agent)
|
|
13
|
+
- [Search Monitors](#search-monitors)
|
|
13
14
|
- [Error Handling](#error-handling)
|
|
14
15
|
- [Documentation](#documentation)
|
|
15
16
|
- [Development](#development)
|
|
@@ -134,7 +135,7 @@ client = Exa::Client.new
|
|
|
134
135
|
results = client.search("Ruby programming language")
|
|
135
136
|
results.results.each { |item| puts "#{item['title']}: #{item['url']}" }
|
|
136
137
|
|
|
137
|
-
# Find similar content
|
|
138
|
+
# Find similar content (deprecated: prefer search with a query that describes the page)
|
|
138
139
|
similar = client.find_similar("https://arxiv.org/abs/2307.06435")
|
|
139
140
|
similar.results.each { |item| puts item['url'] }
|
|
140
141
|
|
|
@@ -142,13 +143,19 @@ similar.results.each { |item| puts item['url'] }
|
|
|
142
143
|
answer = client.answer("What is machine learning?")
|
|
143
144
|
puts answer.answer
|
|
144
145
|
|
|
145
|
-
# Find code examples
|
|
146
|
+
# Find code examples (deprecated: /context is not in the API spec)
|
|
146
147
|
code = client.context("React hooks")
|
|
147
148
|
puts code.response
|
|
148
149
|
|
|
149
150
|
# Get page contents
|
|
150
151
|
contents = client.get_contents(["https://ruby-lang.org"])
|
|
151
152
|
puts contents.results.first["text"]
|
|
153
|
+
|
|
154
|
+
# Stream a search with a synthesized answer (requires output_schema)
|
|
155
|
+
schema = { type: "object", properties: { summary: { type: "string" } } }
|
|
156
|
+
client.search_stream("Ruby 3.4 release highlights", output_schema: schema) do |chunk|
|
|
157
|
+
print chunk["delta"] if chunk["type"] == "text-delta"
|
|
158
|
+
end
|
|
152
159
|
```
|
|
153
160
|
|
|
154
161
|
### Command Line
|
|
@@ -156,48 +163,13 @@ puts contents.results.first["text"]
|
|
|
156
163
|
```bash
|
|
157
164
|
# Core Search Commands
|
|
158
165
|
exa-ai search "Ruby programming language"
|
|
159
|
-
exa-ai find-similar "https://arxiv.org/abs/2307.06435"
|
|
166
|
+
exa-ai find-similar "https://arxiv.org/abs/2307.06435" # deprecated
|
|
160
167
|
exa-ai answer "What is machine learning?"
|
|
161
|
-
exa-ai context "React hooks" --tokens-num 5000
|
|
168
|
+
exa-ai context "React hooks" --tokens-num 5000 # deprecated
|
|
162
169
|
exa-ai get-contents "https://ruby-lang.org"
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
exa-ai
|
|
166
|
-
exa-ai webset-list --limit 5
|
|
167
|
-
exa-ai webset-get WEBSET_ID
|
|
168
|
-
exa-ai webset-update WEBSET_ID --metadata '{"updated":"true","version":"2"}'
|
|
169
|
-
exa-ai webset-delete WEBSET_ID --force
|
|
170
|
-
exa-ai webset-cancel WEBSET_ID
|
|
171
|
-
|
|
172
|
-
# Webset Searches
|
|
173
|
-
exa-ai webset-search-create WEBSET_ID --query "Ford Mustang" --entity custom --entity-description "vintage cars"
|
|
174
|
-
exa-ai webset-search-create WEBSET_ID --query "tech CEOs" --entity person --count 20
|
|
175
|
-
exa-ai webset-search-create WEBSET_ID --query "Y Combinator startups" --entity company
|
|
176
|
-
exa-ai webset-search-get WEBSET_ID SEARCH_ID
|
|
177
|
-
exa-ai webset-search-cancel WEBSET_ID SEARCH_ID
|
|
178
|
-
|
|
179
|
-
# Webset Items
|
|
180
|
-
exa-ai webset-item-list WEBSET_ID
|
|
181
|
-
exa-ai webset-item-get WEBSET_ID ITEM_ID
|
|
182
|
-
exa-ai webset-item-delete WEBSET_ID ITEM_ID --force
|
|
183
|
-
|
|
184
|
-
# Enrichments
|
|
185
|
-
exa-ai enrichment-create WEBSET_ID --description "Find company email" --format text
|
|
186
|
-
exa-ai enrichment-create WEBSET_ID --description "Company size category" --format options --options '[{"label":"Small (1-10)"},{"label":"Medium (11-50)"},{"label":"Large (51+)"}]'
|
|
187
|
-
exa-ai enrichment-list WEBSET_ID
|
|
188
|
-
exa-ai enrichment-get WEBSET_ID ENRICHMENT_ID
|
|
189
|
-
exa-ai enrichment-update WEBSET_ID ENRICHMENT_ID --description "Updated description"
|
|
190
|
-
exa-ai enrichment-delete WEBSET_ID ENRICHMENT_ID --force
|
|
191
|
-
exa-ai enrichment-cancel WEBSET_ID ENRICHMENT_ID
|
|
192
|
-
|
|
193
|
-
# Webset Imports
|
|
194
|
-
exa-ai webset-import-create companies.csv --count 100 --title "My Companies" --format csv --entity-type company
|
|
195
|
-
exa-ai webset-import-create data.csv --count 50 --title "Tech Startups" --format csv --entity-type company --csv-identifier 0
|
|
196
|
-
exa-ai webset-import-create import.csv --count 100 --title "Import" --format csv --entity-type company --metadata '{"source":"crm"}' --quiet
|
|
197
|
-
exa-ai webset-import-list
|
|
198
|
-
exa-ai webset-import-get IMPORT_ID
|
|
199
|
-
exa-ai webset-import-update IMPORT_ID --title "Updated Title"
|
|
200
|
-
exa-ai webset-import-delete IMPORT_ID
|
|
170
|
+
exa-ai search "climate tech seed rounds" --type lite --objective "Find primary sources"
|
|
171
|
+
exa-ai get-contents --ids DOC_ID_1,DOC_ID_2 --highlights --highlights-verbosity low
|
|
172
|
+
exa-ai answer "What is machine learning?" --model exa-pro --user-location US
|
|
201
173
|
```
|
|
202
174
|
|
|
203
175
|
## Features
|
|
@@ -206,17 +178,27 @@ The gem provides complete access to Exa's API endpoints:
|
|
|
206
178
|
|
|
207
179
|
### Core Search
|
|
208
180
|
- **Search** — Neural and keyword search across billions of web pages
|
|
209
|
-
- **Find Similar** — Discover content similar to a given URL
|
|
181
|
+
- **Find Similar** (deprecated) — Discover content similar to a given URL
|
|
210
182
|
- **Answer** — Generate comprehensive answers with source citations
|
|
211
|
-
- **Context** — Find relevant code and documentation snippets
|
|
183
|
+
- **Context** (deprecated) — Find relevant code and documentation snippets
|
|
212
184
|
- **Get Contents** — Extract full text content from web pages
|
|
213
185
|
|
|
214
|
-
###
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
-
|
|
219
|
-
-
|
|
186
|
+
### Deprecated and legacy options
|
|
187
|
+
|
|
188
|
+
These still work, so existing code keeps running. The search command prints the API's `warnings` to stderr when the API flags one of them. Use the replacement in new code.
|
|
189
|
+
|
|
190
|
+
- `find_similar` / `exa-ai find-similar`: deprecated by the API. Use `search` with a query that describes the source page.
|
|
191
|
+
- `context` / `exa-ai context`: `/context` is not in the API spec. No replacement is named; for code lookup, use `search`.
|
|
192
|
+
- Search types `fast` and `instant` are legacy; use `lite`. `deep-reasoning` is legacy; use `deep`.
|
|
193
|
+
- `start_crawl_date` and `end_crawl_date` are deprecated. The API ignores them.
|
|
194
|
+
- `include_text` and `exclude_text` are deprecated.
|
|
195
|
+
- The `context` contents option and the `context` response field are deprecated. Use `highlights` or `text`.
|
|
196
|
+
- `highlights` `num_sentences` and `highlights_per_url` are deprecated. Use `max_characters`.
|
|
197
|
+
- `subpages` and `subpage_target` are deprecated on `search` and `find_similar`. They stay valid on `get_contents`.
|
|
198
|
+
- The `resolved_search_type` response field is deprecated.
|
|
199
|
+
- The CLI no longer accepts `--category github`; it is not in the API's category list.
|
|
200
|
+
|
|
201
|
+
See [docs/API.md](docs/API.md) and [docs/CLI.md](docs/CLI.md) for details.
|
|
220
202
|
|
|
221
203
|
### Agent
|
|
222
204
|
- **Agent API** — Asynchronous research agent with citations, streaming, and full run lifecycle
|
|
@@ -267,7 +249,7 @@ run = client.agent_run_create(
|
|
|
267
249
|
# results into one grounded, structured answer.
|
|
268
250
|
run = client.agent_run_create(
|
|
269
251
|
query: "Profile Anthropic: total funding and estimated monthly web traffic",
|
|
270
|
-
data_sources: [{ provider: "
|
|
252
|
+
data_sources: [{ provider: "fiber" }, { provider: "similarweb" }],
|
|
271
253
|
output_schema: {
|
|
272
254
|
type: "object",
|
|
273
255
|
properties: {
|
|
@@ -278,11 +260,19 @@ run = client.agent_run_create(
|
|
|
278
260
|
}
|
|
279
261
|
)
|
|
280
262
|
|
|
263
|
+
# Limit what a run may spend. max_cost_dollars accepts $1 to $100;
|
|
264
|
+
# max_duration_seconds (300 to 10800) applies only to effort "ultra".
|
|
265
|
+
run = client.agent_run_create(
|
|
266
|
+
query: "Every public company that announced a lithium recycling plant in 2025",
|
|
267
|
+
effort: "ultra",
|
|
268
|
+
budget: { max_cost_dollars: 20.0, max_duration_seconds: 3600 }
|
|
269
|
+
)
|
|
270
|
+
|
|
281
271
|
# Stream events as they arrive
|
|
282
|
-
client.agent_run_stream(query: "AI infrastructure startups that raised Series A in 2025") do |event, data|
|
|
283
|
-
puts "#{event}: #{data.inspect}"
|
|
272
|
+
client.agent_run_stream(query: "AI infrastructure startups that raised Series A in 2025") do |event, data, event_id|
|
|
273
|
+
puts "#{event} (#{event_id}): #{data.inspect}"
|
|
284
274
|
# event is the SSE event-type string, e.g. "agent_run.completed"
|
|
285
|
-
# data is the parsed JSON hash
|
|
275
|
+
# data is the parsed JSON hash; event_id is the SSE id, or nil
|
|
286
276
|
end
|
|
287
277
|
|
|
288
278
|
# List recent runs
|
|
@@ -294,12 +284,21 @@ runs.data.each { |r| puts "#{r.id}: #{r.status}" }
|
|
|
294
284
|
# Fetch a run's events
|
|
295
285
|
events = client.agent_run_events(run.id)
|
|
296
286
|
|
|
297
|
-
#
|
|
287
|
+
# Replay the events after a known event id (server-sent events).
|
|
288
|
+
# This reads the whole response before it returns.
|
|
289
|
+
events = client.agent_run_events(run.id, last_event_id: "7")
|
|
290
|
+
|
|
291
|
+
# Stop a run early: it completes with stop_reason "stopped" and keeps the
|
|
292
|
+
# results gathered so far (effort high, xhigh or ultra only)
|
|
293
|
+
client.agent_run_stop(run.id)
|
|
294
|
+
|
|
295
|
+
# Cancel a run (it ends at once with no results), or delete it
|
|
298
296
|
client.agent_run_cancel(run.id)
|
|
299
|
-
client.agent_run_delete(run.id)
|
|
297
|
+
deletion = client.agent_run_delete(run.id) # => Exa::Resources::AgentRunDeletion
|
|
298
|
+
deletion.deleted? # => true
|
|
300
299
|
```
|
|
301
300
|
|
|
302
|
-
> **Note:**
|
|
301
|
+
> **Note:** The gem converts snake_case keys to camelCase at every depth, including keys inside `input` and `data_sources` items. Keys under `output_schema`, `schema`, `metadata`, `data` and `exclusion` are your own data and are sent unchanged, so supply them in the exact shape the API expects.
|
|
303
302
|
|
|
304
303
|
### Command Line
|
|
305
304
|
|
|
@@ -309,24 +308,82 @@ exa-ai agent-run-create --query "AI infrastructure startups that raised Series A
|
|
|
309
308
|
|
|
310
309
|
# Attach premium data partners (Exa Connect) with a structured schema.
|
|
311
310
|
# Run `exa-ai agent-run-create --help` to see every provider and when to use it:
|
|
312
|
-
#
|
|
311
|
+
# fiber, similarweb, baselayer, polymarket, macrobond, affiliate, particle,
|
|
312
|
+
# financial_datasets, jinko (up to 5 per run)
|
|
313
313
|
exa-ai agent-run-create --wait \
|
|
314
314
|
--query "Profile Anthropic: total funding and monthly web traffic" \
|
|
315
|
-
--data-sources
|
|
315
|
+
--data-sources fiber,similarweb \
|
|
316
316
|
--output-schema '{"type":"object","properties":{"name":{"type":"string"},"totalFunding":{"type":"string"},"monthlyVisits":{"type":"number"}}}'
|
|
317
317
|
|
|
318
|
+
# Cap cost and time for an ultra run
|
|
319
|
+
exa-ai agent-run-create --effort ultra --max-cost-dollars 20 --max-duration-seconds 3600 \
|
|
320
|
+
--query "Every public company that announced a lithium recycling plant in 2025"
|
|
321
|
+
|
|
318
322
|
# Fetch an existing run
|
|
319
323
|
exa-ai agent-run-get <run_id>
|
|
320
324
|
|
|
321
325
|
# List recent runs
|
|
322
326
|
exa-ai agent-run-list --limit 5
|
|
323
327
|
|
|
324
|
-
#
|
|
328
|
+
# Stop a run early and keep its results, or cancel or delete it
|
|
329
|
+
exa-ai agent-run-stop <run_id>
|
|
325
330
|
exa-ai agent-run-cancel <run_id>
|
|
326
331
|
exa-ai agent-run-delete <run_id>
|
|
327
332
|
|
|
328
|
-
# Fetch a run's events
|
|
329
|
-
exa-ai agent-run-events <run_id>
|
|
333
|
+
# Fetch a run's events, one page at a time
|
|
334
|
+
exa-ai agent-run-events <run_id> --limit 50
|
|
335
|
+
exa-ai agent-run-events <run_id> --limit 50 --cursor <next_cursor>
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
## Search Monitors
|
|
339
|
+
|
|
340
|
+
A search monitor runs an Exa search on a schedule and posts new results to your webhook. This is the Monitors API (`/monitors`).
|
|
341
|
+
|
|
342
|
+
### Ruby API
|
|
343
|
+
|
|
344
|
+
```ruby
|
|
345
|
+
client = Exa::Client.new(api_key: "your-key")
|
|
346
|
+
|
|
347
|
+
# Create a monitor that runs once a day.
|
|
348
|
+
# Without trigger:, the monitor runs only when you call search_monitor_trigger.
|
|
349
|
+
monitor = client.search_monitor_create(
|
|
350
|
+
name: "AI funding news",
|
|
351
|
+
search: { query: "AI/ML infrastructure startups with Series A funding", num_results: 10 },
|
|
352
|
+
webhook: { url: "https://your-app.example/webhooks/exa" },
|
|
353
|
+
trigger: { type: "interval", period: "1d" }
|
|
354
|
+
)
|
|
355
|
+
monitor.webhook_secret # The API returns this only once. Store it now.
|
|
356
|
+
|
|
357
|
+
client.search_monitor_get(monitor.id)
|
|
358
|
+
client.search_monitor_list(status: "active", limit: 20)
|
|
359
|
+
client.search_monitor_update(monitor.id, status: "paused")
|
|
360
|
+
client.search_monitor_update(monitor.id, trigger: nil) # remove the schedule
|
|
361
|
+
client.search_monitor_trigger(monitor.id) # run now
|
|
362
|
+
|
|
363
|
+
runs = client.search_monitor_runs_list(monitor.id)
|
|
364
|
+
client.search_monitor_runs_get(monitor.id, runs.data.first.id)
|
|
365
|
+
|
|
366
|
+
# Pause, unpause or delete many monitors. This is a dry run unless you pass dry_run: false.
|
|
367
|
+
result = client.search_monitor_batch(action: "pause", filter: { name: "AI funding" })
|
|
368
|
+
result.ids # what would change
|
|
369
|
+
|
|
370
|
+
client.search_monitor_delete(monitor.id)
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
### Command Line
|
|
374
|
+
|
|
375
|
+
```bash
|
|
376
|
+
exa-ai search-monitor-create --query "AI/ML infrastructure startups with Series A funding" \
|
|
377
|
+
--webhook-url https://your-app.example/webhooks/exa --period 1d --name "AI funding news"
|
|
378
|
+
exa-ai search-monitor-list --status active
|
|
379
|
+
exa-ai search-monitor-get <monitor_id>
|
|
380
|
+
exa-ai search-monitor-update <monitor_id> --status paused
|
|
381
|
+
exa-ai search-monitor-trigger <monitor_id>
|
|
382
|
+
exa-ai search-monitor-runs-list <monitor_id>
|
|
383
|
+
exa-ai search-monitor-runs-get <monitor_id> <run_id>
|
|
384
|
+
exa-ai search-monitor-batch --action pause --name "AI funding" # dry run
|
|
385
|
+
exa-ai search-monitor-batch --action pause --name "AI funding" --execute # apply
|
|
386
|
+
exa-ai search-monitor-delete <monitor_id>
|
|
330
387
|
```
|
|
331
388
|
|
|
332
389
|
## Error Handling
|
|
@@ -371,9 +428,6 @@ bundle exec rake test
|
|
|
371
428
|
|
|
372
429
|
# Run integration tests (VCR-based, no real API calls)
|
|
373
430
|
RUN_INTEGRATION_TESTS=true bundle exec rake test
|
|
374
|
-
|
|
375
|
-
# Run CLI integration tests (real API calls, requires explicit opt-in)
|
|
376
|
-
RUN_CLI_INTEGRATION_TESTS=true bundle exec rake test
|
|
377
431
|
```
|
|
378
432
|
|
|
379
433
|
### Integration Tests
|
|
@@ -386,20 +440,12 @@ RUN_CLI_INTEGRATION_TESTS=true bundle exec rake test
|
|
|
386
440
|
- Set `RUN_INTEGRATION_TESTS=true` to run them
|
|
387
441
|
- Safe to run during development
|
|
388
442
|
|
|
389
|
-
**CLI integration tests (`RUN_CLI_INTEGRATION_TESTS`):**
|
|
390
|
-
- Make real API calls through shell commands
|
|
391
|
-
- Consume Exa's concurrent search quota
|
|
392
|
-
- Set `RUN_CLI_INTEGRATION_TESTS=true` AND `EXA_API_KEY` to run them
|
|
393
|
-
- **Warning:** Can exhaust API quota and trigger rate limits lasting 1-2 days
|
|
394
|
-
|
|
395
443
|
**When to run integration tests:**
|
|
396
444
|
- VCR tests: Anytime (safe, no real API calls)
|
|
397
|
-
- CLI tests: Only before releases or when testing CLI-specific functionality
|
|
398
445
|
|
|
399
446
|
**Test Coverage:**
|
|
400
447
|
- **Unit tests** - Fast, no API calls, always run
|
|
401
448
|
- **VCR integration tests** - Replay cassettes, skipped by default
|
|
402
|
-
- **CLI integration tests** - Real API calls via shell, skipped by default
|
|
403
449
|
|
|
404
450
|
## Support
|
|
405
451
|
|
data/exe/exa-ai
CHANGED
|
@@ -12,40 +12,20 @@ module ExaCLI
|
|
|
12
12
|
"answer" => "Generate an answer to a question",
|
|
13
13
|
"context" => "Get code context from repositories",
|
|
14
14
|
"get-contents" => "Retrieve page contents",
|
|
15
|
-
"
|
|
16
|
-
"
|
|
17
|
-
"
|
|
18
|
-
"
|
|
19
|
-
"
|
|
20
|
-
"
|
|
21
|
-
"
|
|
22
|
-
"
|
|
23
|
-
"
|
|
24
|
-
"webset-item-list" => "List items in a webset",
|
|
25
|
-
"webset-item-get" => "Get webset item details",
|
|
26
|
-
"webset-item-delete" => "Delete a webset item",
|
|
27
|
-
"enrichment-create" => "Create an enrichment",
|
|
28
|
-
"enrichment-get" => "Get enrichment details",
|
|
29
|
-
"enrichment-list" => "List enrichments",
|
|
30
|
-
"enrichment-update" => "Update an enrichment",
|
|
31
|
-
"enrichment-delete" => "Delete an enrichment",
|
|
32
|
-
"enrichment-cancel" => "Cancel an enrichment",
|
|
33
|
-
"import-create" => "Create a new import",
|
|
34
|
-
"import-list" => "List imports",
|
|
35
|
-
"import-get" => "Get import details",
|
|
36
|
-
"import-update" => "Update an import",
|
|
37
|
-
"import-delete" => "Delete an import",
|
|
38
|
-
"monitor-create" => "Create a webset monitor",
|
|
39
|
-
"monitor-get" => "Get monitor details",
|
|
40
|
-
"monitor-list" => "List monitors",
|
|
41
|
-
"monitor-update" => "Update a monitor",
|
|
42
|
-
"monitor-delete" => "Delete a monitor",
|
|
43
|
-
"monitor-runs-list" => "List monitor runs",
|
|
44
|
-
"monitor-runs-get" => "Get monitor run details",
|
|
15
|
+
"search-monitor-create" => "Create a search monitor",
|
|
16
|
+
"search-monitor-get" => "Get search monitor details",
|
|
17
|
+
"search-monitor-list" => "List search monitors",
|
|
18
|
+
"search-monitor-update" => "Update a search monitor",
|
|
19
|
+
"search-monitor-delete" => "Delete a search monitor",
|
|
20
|
+
"search-monitor-trigger" => "Run a search monitor now",
|
|
21
|
+
"search-monitor-batch" => "Delete, pause or unpause search monitors in bulk",
|
|
22
|
+
"search-monitor-runs-list" => "List search monitor runs",
|
|
23
|
+
"search-monitor-runs-get" => "Get search monitor run details",
|
|
45
24
|
"agent-run-create" => "Create an agent run",
|
|
46
25
|
"agent-run-get" => "Get agent run details",
|
|
47
26
|
"agent-run-list" => "List agent runs",
|
|
48
27
|
"agent-run-cancel" => "Cancel an agent run",
|
|
28
|
+
"agent-run-stop" => "Stop an agent run early and keep its results",
|
|
49
29
|
"agent-run-delete" => "Delete an agent run",
|
|
50
30
|
"agent-run-events" => "Get events for an agent run"
|
|
51
31
|
}.freeze
|
|
@@ -71,66 +51,24 @@ module ExaCLI
|
|
|
71
51
|
exec File.expand_path("../exa-ai-context", __FILE__), *ARGV[1..]
|
|
72
52
|
when "get-contents"
|
|
73
53
|
exec File.expand_path("../exa-ai-get-contents", __FILE__), *ARGV[1..]
|
|
74
|
-
when "
|
|
75
|
-
exec File.expand_path("../exa-ai-
|
|
76
|
-
when "
|
|
77
|
-
exec File.expand_path("../exa-ai-
|
|
78
|
-
when "
|
|
79
|
-
exec File.expand_path("../exa-ai-
|
|
80
|
-
when "
|
|
81
|
-
exec File.expand_path("../exa-ai-
|
|
82
|
-
when "
|
|
83
|
-
exec File.expand_path("../exa-ai-
|
|
84
|
-
when "
|
|
85
|
-
exec File.expand_path("../exa-ai-
|
|
86
|
-
when "
|
|
87
|
-
exec File.expand_path("../exa-ai-
|
|
88
|
-
when "
|
|
89
|
-
exec File.expand_path("../exa-ai-
|
|
90
|
-
when "
|
|
91
|
-
exec File.expand_path("../exa-ai-
|
|
92
|
-
when "webset-item-list"
|
|
93
|
-
exec File.expand_path("../exa-ai-webset-item-list", __FILE__), *ARGV[1..]
|
|
94
|
-
when "webset-item-get"
|
|
95
|
-
exec File.expand_path("../exa-ai-webset-item-get", __FILE__), *ARGV[1..]
|
|
96
|
-
when "webset-item-delete"
|
|
97
|
-
exec File.expand_path("../exa-ai-webset-item-delete", __FILE__), *ARGV[1..]
|
|
98
|
-
when "enrichment-create"
|
|
99
|
-
exec File.expand_path("../exa-ai-enrichment-create", __FILE__), *ARGV[1..]
|
|
100
|
-
when "enrichment-get"
|
|
101
|
-
exec File.expand_path("../exa-ai-enrichment-get", __FILE__), *ARGV[1..]
|
|
102
|
-
when "enrichment-list"
|
|
103
|
-
exec File.expand_path("../exa-ai-enrichment-list", __FILE__), *ARGV[1..]
|
|
104
|
-
when "enrichment-update"
|
|
105
|
-
exec File.expand_path("../exa-ai-enrichment-update", __FILE__), *ARGV[1..]
|
|
106
|
-
when "enrichment-delete"
|
|
107
|
-
exec File.expand_path("../exa-ai-enrichment-delete", __FILE__), *ARGV[1..]
|
|
108
|
-
when "enrichment-cancel"
|
|
109
|
-
exec File.expand_path("../exa-ai-enrichment-cancel", __FILE__), *ARGV[1..]
|
|
110
|
-
when "import-create"
|
|
111
|
-
exec File.expand_path("../exa-ai-import-create", __FILE__), *ARGV[1..]
|
|
112
|
-
when "import-list"
|
|
113
|
-
exec File.expand_path("../exa-ai-import-list", __FILE__), *ARGV[1..]
|
|
114
|
-
when "import-get"
|
|
115
|
-
exec File.expand_path("../exa-ai-import-get", __FILE__), *ARGV[1..]
|
|
116
|
-
when "import-update"
|
|
117
|
-
exec File.expand_path("../exa-ai-import-update", __FILE__), *ARGV[1..]
|
|
118
|
-
when "import-delete"
|
|
119
|
-
exec File.expand_path("../exa-ai-import-delete", __FILE__), *ARGV[1..]
|
|
120
|
-
when "monitor-create"
|
|
121
|
-
exec File.expand_path("../exa-ai-monitor-create", __FILE__), *ARGV[1..]
|
|
122
|
-
when "monitor-get"
|
|
123
|
-
exec File.expand_path("../exa-ai-monitor-get", __FILE__), *ARGV[1..]
|
|
124
|
-
when "monitor-list"
|
|
125
|
-
exec File.expand_path("../exa-ai-monitor-list", __FILE__), *ARGV[1..]
|
|
126
|
-
when "monitor-update"
|
|
127
|
-
exec File.expand_path("../exa-ai-monitor-update", __FILE__), *ARGV[1..]
|
|
128
|
-
when "monitor-delete"
|
|
129
|
-
exec File.expand_path("../exa-ai-monitor-delete", __FILE__), *ARGV[1..]
|
|
130
|
-
when "monitor-runs-list"
|
|
131
|
-
exec File.expand_path("../exa-ai-monitor-runs-list", __FILE__), *ARGV[1..]
|
|
132
|
-
when "monitor-runs-get"
|
|
133
|
-
exec File.expand_path("../exa-ai-monitor-runs-get", __FILE__), *ARGV[1..]
|
|
54
|
+
when "search-monitor-create"
|
|
55
|
+
exec File.expand_path("../exa-ai-search-monitor-create", __FILE__), *ARGV[1..]
|
|
56
|
+
when "search-monitor-get"
|
|
57
|
+
exec File.expand_path("../exa-ai-search-monitor-get", __FILE__), *ARGV[1..]
|
|
58
|
+
when "search-monitor-list"
|
|
59
|
+
exec File.expand_path("../exa-ai-search-monitor-list", __FILE__), *ARGV[1..]
|
|
60
|
+
when "search-monitor-update"
|
|
61
|
+
exec File.expand_path("../exa-ai-search-monitor-update", __FILE__), *ARGV[1..]
|
|
62
|
+
when "search-monitor-delete"
|
|
63
|
+
exec File.expand_path("../exa-ai-search-monitor-delete", __FILE__), *ARGV[1..]
|
|
64
|
+
when "search-monitor-trigger"
|
|
65
|
+
exec File.expand_path("../exa-ai-search-monitor-trigger", __FILE__), *ARGV[1..]
|
|
66
|
+
when "search-monitor-batch"
|
|
67
|
+
exec File.expand_path("../exa-ai-search-monitor-batch", __FILE__), *ARGV[1..]
|
|
68
|
+
when "search-monitor-runs-list"
|
|
69
|
+
exec File.expand_path("../exa-ai-search-monitor-runs-list", __FILE__), *ARGV[1..]
|
|
70
|
+
when "search-monitor-runs-get"
|
|
71
|
+
exec File.expand_path("../exa-ai-search-monitor-runs-get", __FILE__), *ARGV[1..]
|
|
134
72
|
when "agent-run-create"
|
|
135
73
|
exec File.expand_path("../exa-ai-agent-run-create", __FILE__), *ARGV[1..]
|
|
136
74
|
when "agent-run-get"
|
|
@@ -139,6 +77,8 @@ module ExaCLI
|
|
|
139
77
|
exec File.expand_path("../exa-ai-agent-run-list", __FILE__), *ARGV[1..]
|
|
140
78
|
when "agent-run-cancel"
|
|
141
79
|
exec File.expand_path("../exa-ai-agent-run-cancel", __FILE__), *ARGV[1..]
|
|
80
|
+
when "agent-run-stop"
|
|
81
|
+
exec File.expand_path("../exa-ai-agent-run-stop", __FILE__), *ARGV[1..]
|
|
142
82
|
when "agent-run-delete"
|
|
143
83
|
exec File.expand_path("../exa-ai-agent-run-delete", __FILE__), *ARGV[1..]
|
|
144
84
|
when "agent-run-events"
|
|
@@ -166,61 +106,26 @@ module ExaCLI
|
|
|
166
106
|
["get-contents", "Retrieve page contents"]
|
|
167
107
|
])
|
|
168
108
|
|
|
169
|
-
print_command_section("Websets", [
|
|
170
|
-
["webset-create", "Create a new webset"],
|
|
171
|
-
["webset-get", "Get webset details"],
|
|
172
|
-
["webset-list", "List websets"],
|
|
173
|
-
["webset-update", "Update a webset"],
|
|
174
|
-
["webset-delete", "Delete a webset"],
|
|
175
|
-
["webset-cancel", "Cancel a webset"]
|
|
176
|
-
])
|
|
177
|
-
|
|
178
|
-
print_command_section("Webset Searches", [
|
|
179
|
-
["webset-search-create", "Create a search in a webset"],
|
|
180
|
-
["webset-search-get", "Get webset search details"],
|
|
181
|
-
["webset-search-cancel", "Cancel a webset search"]
|
|
182
|
-
])
|
|
183
|
-
|
|
184
|
-
print_command_section("Webset Items", [
|
|
185
|
-
["webset-item-list", "List items in a webset"],
|
|
186
|
-
["webset-item-get", "Get webset item details"],
|
|
187
|
-
["webset-item-delete", "Delete a webset item"]
|
|
188
|
-
])
|
|
189
|
-
|
|
190
|
-
print_command_section("Webset Enrichments", [
|
|
191
|
-
["enrichment-create", "Create an enrichment"],
|
|
192
|
-
["enrichment-get", "Get enrichment details"],
|
|
193
|
-
["enrichment-list", "List enrichments"],
|
|
194
|
-
["enrichment-update", "Update an enrichment"],
|
|
195
|
-
["enrichment-delete", "Delete an enrichment"],
|
|
196
|
-
["enrichment-cancel", "Cancel an enrichment"]
|
|
197
|
-
])
|
|
198
|
-
|
|
199
|
-
print_command_section("Imports", [
|
|
200
|
-
["import-create", "Create a new import"],
|
|
201
|
-
["import-list", "List imports"],
|
|
202
|
-
["import-get", "Get import details"],
|
|
203
|
-
["import-update", "Update an import"],
|
|
204
|
-
["import-delete", "Delete an import"]
|
|
205
|
-
])
|
|
206
|
-
|
|
207
109
|
print_command_section("Agent Runs", [
|
|
208
110
|
["agent-run-create", "Create an agent run"],
|
|
209
111
|
["agent-run-get", "Get agent run details"],
|
|
210
112
|
["agent-run-list", "List agent runs"],
|
|
211
113
|
["agent-run-cancel", "Cancel an agent run"],
|
|
114
|
+
["agent-run-stop", "Stop an agent run early and keep its results"],
|
|
212
115
|
["agent-run-delete", "Delete an agent run"],
|
|
213
116
|
["agent-run-events", "Get events for an agent run"]
|
|
214
117
|
])
|
|
215
118
|
|
|
216
|
-
print_command_section("
|
|
217
|
-
["monitor-create", "Create a
|
|
218
|
-
["monitor-get", "Get monitor details"],
|
|
219
|
-
["monitor-list", "List monitors"],
|
|
220
|
-
["monitor-update", "Update a monitor"],
|
|
221
|
-
["monitor-delete", "Delete a monitor"],
|
|
222
|
-
["monitor-
|
|
223
|
-
["monitor-
|
|
119
|
+
print_command_section("Search Monitors", [
|
|
120
|
+
["search-monitor-create", "Create a search monitor"],
|
|
121
|
+
["search-monitor-get", "Get search monitor details"],
|
|
122
|
+
["search-monitor-list", "List search monitors"],
|
|
123
|
+
["search-monitor-update", "Update a search monitor"],
|
|
124
|
+
["search-monitor-delete", "Delete a search monitor"],
|
|
125
|
+
["search-monitor-trigger", "Run a search monitor now"],
|
|
126
|
+
["search-monitor-batch", "Delete, pause or unpause search monitors in bulk"],
|
|
127
|
+
["search-monitor-runs-list", "List search monitor runs"],
|
|
128
|
+
["search-monitor-runs-get", "Get search monitor run details"]
|
|
224
129
|
])
|
|
225
130
|
|
|
226
131
|
puts "Global Options:"
|