exa-ai 0.12.2 → 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.
Files changed (159) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +120 -83
  3. data/exe/exa-ai +45 -152
  4. data/exe/exa-ai-agent-run-create +55 -20
  5. data/exe/exa-ai-agent-run-delete +1 -8
  6. data/exe/exa-ai-agent-run-events +21 -1
  7. data/exe/exa-ai-agent-run-list +1 -1
  8. data/exe/{exa-ai-research-list → exa-ai-agent-run-stop} +31 -32
  9. data/exe/exa-ai-answer +25 -0
  10. data/exe/exa-ai-context +6 -2
  11. data/exe/exa-ai-find-similar +26 -68
  12. data/exe/exa-ai-get-contents +138 -42
  13. data/exe/exa-ai-search +27 -104
  14. data/exe/exa-ai-search-monitor-batch +93 -0
  15. data/exe/exa-ai-search-monitor-create +104 -0
  16. data/exe/exa-ai-search-monitor-delete +69 -0
  17. data/exe/exa-ai-search-monitor-get +69 -0
  18. data/exe/exa-ai-search-monitor-list +73 -0
  19. data/exe/exa-ai-search-monitor-runs-get +68 -0
  20. data/exe/exa-ai-search-monitor-runs-list +75 -0
  21. data/exe/exa-ai-search-monitor-trigger +69 -0
  22. data/exe/exa-ai-search-monitor-update +102 -0
  23. data/lib/exa/cli/base.rb +57 -0
  24. data/lib/exa/cli/contents_flags.rb +199 -0
  25. data/lib/exa/cli/formatters/agent_run_formatter.rb +79 -3
  26. data/lib/exa/cli/formatters/search_formatter.rb +18 -2
  27. data/lib/exa/cli/formatters/search_monitor_formatter.rb +98 -0
  28. data/lib/exa/cli/search_parser.rb +46 -87
  29. data/lib/exa/client.rb +183 -333
  30. data/lib/exa/middleware/raise_error.rb +14 -0
  31. data/lib/exa/resources/agent_run.rb +5 -3
  32. data/lib/exa/resources/agent_run_deletion.rb +17 -0
  33. data/lib/exa/resources/answer.rb +3 -3
  34. data/lib/exa/resources/contents_result.rb +5 -1
  35. data/lib/exa/resources/find_similar_result.rb +5 -1
  36. data/lib/exa/resources/search_monitor.rb +42 -0
  37. data/lib/exa/resources/search_monitor_batch_result.rb +11 -0
  38. data/lib/exa/resources/{research_list.rb → search_monitor_list.rb} +3 -2
  39. data/lib/exa/resources/search_monitor_run.rb +46 -0
  40. data/lib/exa/resources/search_monitor_trigger_result.rb +11 -0
  41. data/lib/exa/resources/search_result.rb +11 -1
  42. data/lib/exa/services/agent_run_cancel.rb +1 -12
  43. data/lib/exa/services/agent_run_create.rb +1 -12
  44. data/lib/exa/services/agent_run_delete.rb +6 -14
  45. data/lib/exa/services/agent_run_events.rb +33 -4
  46. data/lib/exa/services/agent_run_get.rb +1 -12
  47. data/lib/exa/services/agent_run_list.rb +1 -12
  48. data/lib/exa/services/agent_run_stop.rb +21 -0
  49. data/lib/exa/services/agent_run_stream.rb +56 -52
  50. data/lib/exa/services/answer.rb +5 -2
  51. data/lib/exa/services/answer_stream.rb +57 -46
  52. data/lib/exa/services/context.rb +3 -1
  53. data/lib/exa/services/find_similar.rb +9 -2
  54. data/lib/exa/services/get_contents.rb +14 -15
  55. data/lib/exa/services/parameter_converter.rb +128 -111
  56. data/lib/exa/services/search.rb +58 -19
  57. data/lib/exa/services/search_monitors/batch.rb +36 -0
  58. data/lib/exa/services/search_monitors/create.rb +37 -0
  59. data/lib/exa/services/search_monitors/delete.rb +22 -0
  60. data/lib/exa/services/search_monitors/get.rb +22 -0
  61. data/lib/exa/services/search_monitors/list.rb +29 -0
  62. data/lib/exa/services/search_monitors/runs_get.rb +23 -0
  63. data/lib/exa/services/search_monitors/runs_list.rb +29 -0
  64. data/lib/exa/services/search_monitors/trigger.rb +22 -0
  65. data/lib/exa/services/search_monitors/update.rb +42 -0
  66. data/lib/exa/services/search_stream.rb +38 -0
  67. data/lib/exa/version.rb +1 -1
  68. data/lib/exa.rb +18 -56
  69. metadata +31 -94
  70. data/exe/exa-ai-enrichment-cancel +0 -108
  71. data/exe/exa-ai-enrichment-create +0 -226
  72. data/exe/exa-ai-enrichment-delete +0 -122
  73. data/exe/exa-ai-enrichment-get +0 -104
  74. data/exe/exa-ai-enrichment-list +0 -99
  75. data/exe/exa-ai-enrichment-update +0 -171
  76. data/exe/exa-ai-import-create +0 -253
  77. data/exe/exa-ai-import-delete +0 -92
  78. data/exe/exa-ai-import-get +0 -92
  79. data/exe/exa-ai-import-list +0 -72
  80. data/exe/exa-ai-import-update +0 -164
  81. data/exe/exa-ai-monitor-create +0 -223
  82. data/exe/exa-ai-monitor-delete +0 -101
  83. data/exe/exa-ai-monitor-get +0 -92
  84. data/exe/exa-ai-monitor-list +0 -90
  85. data/exe/exa-ai-monitor-runs-get +0 -103
  86. data/exe/exa-ai-monitor-runs-list +0 -110
  87. data/exe/exa-ai-monitor-update +0 -207
  88. data/exe/exa-ai-research-get +0 -109
  89. data/exe/exa-ai-research-start +0 -174
  90. data/exe/exa-ai-webset-cancel +0 -97
  91. data/exe/exa-ai-webset-create +0 -254
  92. data/exe/exa-ai-webset-delete +0 -111
  93. data/exe/exa-ai-webset-get +0 -93
  94. data/exe/exa-ai-webset-item-delete +0 -111
  95. data/exe/exa-ai-webset-item-get +0 -105
  96. data/exe/exa-ai-webset-item-list +0 -108
  97. data/exe/exa-ai-webset-list +0 -91
  98. data/exe/exa-ai-webset-search-cancel +0 -104
  99. data/exe/exa-ai-webset-search-create +0 -247
  100. data/exe/exa-ai-webset-search-get +0 -105
  101. data/exe/exa-ai-webset-update +0 -143
  102. data/lib/exa/cli/formatters/enrichment_formatter.rb +0 -125
  103. data/lib/exa/cli/formatters/import_formatter.rb +0 -153
  104. data/lib/exa/cli/formatters/monitor_formatter.rb +0 -144
  105. data/lib/exa/cli/formatters/monitor_run_formatter.rb +0 -126
  106. data/lib/exa/cli/formatters/research_formatter.rb +0 -124
  107. data/lib/exa/cli/formatters/webset_formatter.rb +0 -134
  108. data/lib/exa/cli/formatters/webset_item_formatter.rb +0 -131
  109. data/lib/exa/cli/formatters/webset_search_formatter.rb +0 -57
  110. data/lib/exa/constants/websets.rb +0 -19
  111. data/lib/exa/resources/import.rb +0 -86
  112. data/lib/exa/resources/import_collection.rb +0 -33
  113. data/lib/exa/resources/monitor.rb +0 -48
  114. data/lib/exa/resources/monitor_collection.rb +0 -30
  115. data/lib/exa/resources/monitor_run.rb +0 -52
  116. data/lib/exa/resources/monitor_run_collection.rb +0 -30
  117. data/lib/exa/resources/research_task.rb +0 -39
  118. data/lib/exa/resources/webset.rb +0 -74
  119. data/lib/exa/resources/webset_collection.rb +0 -33
  120. data/lib/exa/resources/webset_enrichment.rb +0 -71
  121. data/lib/exa/resources/webset_enrichment_collection.rb +0 -28
  122. data/lib/exa/resources/webset_item_collection.rb +0 -33
  123. data/lib/exa/resources/webset_search.rb +0 -112
  124. data/lib/exa/services/research_get.rb +0 -30
  125. data/lib/exa/services/research_list.rb +0 -37
  126. data/lib/exa/services/research_start.rb +0 -26
  127. data/lib/exa/services/websets/cancel.rb +0 -36
  128. data/lib/exa/services/websets/cancel_enrichment.rb +0 -35
  129. data/lib/exa/services/websets/cancel_search.rb +0 -44
  130. data/lib/exa/services/websets/create.rb +0 -45
  131. data/lib/exa/services/websets/create_enrichment.rb +0 -35
  132. data/lib/exa/services/websets/create_search.rb +0 -48
  133. data/lib/exa/services/websets/create_search_validator.rb +0 -128
  134. data/lib/exa/services/websets/create_validator.rb +0 -213
  135. data/lib/exa/services/websets/delete.rb +0 -36
  136. data/lib/exa/services/websets/delete_enrichment.rb +0 -35
  137. data/lib/exa/services/websets/delete_item.rb +0 -20
  138. data/lib/exa/services/websets/get_item.rb +0 -20
  139. data/lib/exa/services/websets/get_search.rb +0 -43
  140. data/lib/exa/services/websets/import_create.rb +0 -40
  141. data/lib/exa/services/websets/import_delete.rb +0 -37
  142. data/lib/exa/services/websets/import_get.rb +0 -37
  143. data/lib/exa/services/websets/import_list.rb +0 -25
  144. data/lib/exa/services/websets/import_update.rb +0 -38
  145. data/lib/exa/services/websets/import_upload.rb +0 -58
  146. data/lib/exa/services/websets/list.rb +0 -25
  147. data/lib/exa/services/websets/list_items.rb +0 -26
  148. data/lib/exa/services/websets/monitors/create.rb +0 -42
  149. data/lib/exa/services/websets/monitors/delete.rb +0 -32
  150. data/lib/exa/services/websets/monitors/get.rb +0 -33
  151. data/lib/exa/services/websets/monitors/list.rb +0 -27
  152. data/lib/exa/services/websets/monitors/runs/get.rb +0 -37
  153. data/lib/exa/services/websets/monitors/runs/list.rb +0 -30
  154. data/lib/exa/services/websets/monitors/update.rb +0 -33
  155. data/lib/exa/services/websets/retrieve.rb +0 -47
  156. data/lib/exa/services/websets/retrieve_enrichment.rb +0 -35
  157. data/lib/exa/services/websets/update.rb +0 -37
  158. data/lib/exa/services/websets/update_enrichment.rb +0 -36
  159. 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: 348823d3dfba08f7525bcc8973ff4f1e8bdcaeb71e82bdc179e4862e5ed2d7fd
4
- data.tar.gz: 670c26f27036aa8d5c9713d1d177e0ef7597f941cd6d3d80ed84127ef2bdb335
3
+ metadata.gz: 4aa92257e4c27dbbd7cd5db638d95d40e76c8d75a92209069a769f1404ace64f
4
+ data.tar.gz: 33b82648f530fd688751fd2f48808b332efc420fcf4f7fd8360f9a2fca476da1
5
5
  SHA512:
6
- metadata.gz: 16a7cc5a2e16127a8ac55da87e1165e8ef71597675459ed17fb534562eccd913f5730fc9bd6225fc9e1b4bad57421fc8675bb7ca592bedc2f66bcba3c7a4e117
7
- data.tar.gz: d1a12ef64c24171dca5726b15163bb858c202a41ecd2aec73a13b8dd37afddc2bb38aea5bcada8002c5cb922f28232db760b959eac61374260149a365c948ebf
6
+ metadata.gz: 4127f458266b07c9f6989eca0a5b8333d98775fa488692af84488ebacfb3104dd23b5eaa5f72f3ab9d606d7ea76746bcb15598d213dc8b7e2154ff6a74f288e7
7
+ data.tar.gz: e8ada14ef4109d77e7c2bbb7647520b441005e68fb4a16c491464877d13d6a80d904b318a6ed8cbe4563de3bfcefd3f26c0c2e85a5f20b6a6eb34bdea18a453b
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # exa-ruby
2
2
 
3
- Ruby client for the Exa.ai API. Search and analyze web content using neural search, question answering, code discovery, and research automation.
3
+ Ruby client for the Exa.ai API. Search and analyze web content using neural search, question answering, code discovery, and agent-based research.
4
4
 
5
5
  ## Table of Contents
6
6
 
@@ -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,53 +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
- # Research Commands
165
- exa-ai research-start --instructions "What species of ant are similar to honeypot ants?"
166
- exa-ai research-get RESEARCH_ID
167
- exa-ai research-list
168
-
169
- # Webset Management
170
- exa-ai webset-create --search '{"query":"technology companies","count":1}'
171
- exa-ai webset-list --limit 5
172
- exa-ai webset-get WEBSET_ID
173
- exa-ai webset-update WEBSET_ID --metadata '{"updated":"true","version":"2"}'
174
- exa-ai webset-delete WEBSET_ID --force
175
- exa-ai webset-cancel WEBSET_ID
176
-
177
- # Webset Searches
178
- exa-ai webset-search-create WEBSET_ID --query "Ford Mustang" --entity custom --entity-description "vintage cars"
179
- exa-ai webset-search-create WEBSET_ID --query "tech CEOs" --entity person --count 20
180
- exa-ai webset-search-create WEBSET_ID --query "Y Combinator startups" --entity company
181
- exa-ai webset-search-get WEBSET_ID SEARCH_ID
182
- exa-ai webset-search-cancel WEBSET_ID SEARCH_ID
183
-
184
- # Webset Items
185
- exa-ai webset-item-list WEBSET_ID
186
- exa-ai webset-item-get WEBSET_ID ITEM_ID
187
- exa-ai webset-item-delete WEBSET_ID ITEM_ID --force
188
-
189
- # Enrichments
190
- exa-ai enrichment-create WEBSET_ID --description "Find company email" --format text
191
- exa-ai enrichment-create WEBSET_ID --description "Company size category" --format options --options '[{"label":"Small (1-10)"},{"label":"Medium (11-50)"},{"label":"Large (51+)"}]'
192
- exa-ai enrichment-list WEBSET_ID
193
- exa-ai enrichment-get WEBSET_ID ENRICHMENT_ID
194
- exa-ai enrichment-update WEBSET_ID ENRICHMENT_ID --description "Updated description"
195
- exa-ai enrichment-delete WEBSET_ID ENRICHMENT_ID --force
196
- exa-ai enrichment-cancel WEBSET_ID ENRICHMENT_ID
197
-
198
- # Webset Imports
199
- exa-ai webset-import-create companies.csv --count 100 --title "My Companies" --format csv --entity-type company
200
- exa-ai webset-import-create data.csv --count 50 --title "Tech Startups" --format csv --entity-type company --csv-identifier 0
201
- exa-ai webset-import-create import.csv --count 100 --title "Import" --format csv --entity-type company --metadata '{"source":"crm"}' --quiet
202
- exa-ai webset-import-list
203
- exa-ai webset-import-get IMPORT_ID
204
- exa-ai webset-import-update IMPORT_ID --title "Updated Title"
205
- 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
206
173
  ```
207
174
 
208
175
  ## Features
@@ -211,28 +178,34 @@ The gem provides complete access to Exa's API endpoints:
211
178
 
212
179
  ### Core Search
213
180
  - **Search** — Neural and keyword search across billions of web pages
214
- - **Find Similar** — Discover content similar to a given URL
181
+ - **Find Similar** (deprecated) — Discover content similar to a given URL
215
182
  - **Answer** — Generate comprehensive answers with source citations
216
- - **Context** — Find relevant code and documentation snippets
183
+ - **Context** (deprecated) — Find relevant code and documentation snippets
217
184
  - **Get Contents** — Extract full text content from web pages
218
185
 
219
- ### Research
220
- - **Research Tasks** — Start and manage long-running research tasks with AI
221
- - **Task Management** — Get status updates and list all research tasks
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.
222
200
 
223
- ### Websets
224
- - **Webset Management** — Create, update, delete, and list datasets of web pages
225
- - **Webset Searches** — Run searches within websets and manage search tasks
226
- - **Webset Items** — List, retrieve, and manage individual items in websets
227
- - **Enrichments** — Create and manage AI-powered data enrichment tasks on websets
228
- - **Imports** — Upload CSV files to import external data into websets
201
+ See [docs/API.md](docs/API.md) and [docs/CLI.md](docs/CLI.md) for details.
229
202
 
230
203
  ### Agent
231
204
  - **Agent API** — Asynchronous research agent with citations, streaming, and full run lifecycle
232
205
 
233
206
  ## Agent
234
207
 
235
- Exa's Agent API runs asynchronous research agents that search the web, synthesize findings, and return structured output with source citations. Runs are long-lived — create one, poll for completion, and stream events as it progresses.
208
+ Exa's Agent API runs asynchronous research agents that search the web, synthesize findings, and return structured output with source citations. Runs are long-lived — create one, poll for completion, and stream events as it progresses. Exa retired the Research API; the Agent API (`exa-ai agent-run-create` and related commands) is its replacement. Pass your prompt as `--query` (Ruby: `query:`), not `--instructions`.
236
209
 
237
210
  ### Ruby API
238
211
 
@@ -276,7 +249,7 @@ run = client.agent_run_create(
276
249
  # results into one grounded, structured answer.
277
250
  run = client.agent_run_create(
278
251
  query: "Profile Anthropic: total funding and estimated monthly web traffic",
279
- data_sources: [{ provider: "fiber_ai" }, { provider: "similarweb" }],
252
+ data_sources: [{ provider: "fiber" }, { provider: "similarweb" }],
280
253
  output_schema: {
281
254
  type: "object",
282
255
  properties: {
@@ -287,11 +260,19 @@ run = client.agent_run_create(
287
260
  }
288
261
  )
289
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
+
290
271
  # Stream events as they arrive
291
- client.agent_run_stream(query: "AI infrastructure startups that raised Series A in 2025") do |event, data|
292
- 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}"
293
274
  # event is the SSE event-type string, e.g. "agent_run.completed"
294
- # data is the parsed JSON hash
275
+ # data is the parsed JSON hash; event_id is the SSE id, or nil
295
276
  end
296
277
 
297
278
  # List recent runs
@@ -303,12 +284,21 @@ runs.data.each { |r| puts "#{r.id}: #{r.status}" }
303
284
  # Fetch a run's events
304
285
  events = client.agent_run_events(run.id)
305
286
 
306
- # Cancel or delete a run
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
307
296
  client.agent_run_cancel(run.id)
308
- client.agent_run_delete(run.id)
297
+ deletion = client.agent_run_delete(run.id) # => Exa::Resources::AgentRunDeletion
298
+ deletion.deleted? # => true
309
299
  ```
310
300
 
311
- > **Note:** Multi-word keys inside `input`, `data_sources` items, and `metadata` are passed through verbatim — supply them in the exact shape the API expects, the same contract as `output_schema`.
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.
312
302
 
313
303
  ### Command Line
314
304
 
@@ -318,24 +308,82 @@ exa-ai agent-run-create --query "AI infrastructure startups that raised Series A
318
308
 
319
309
  # Attach premium data partners (Exa Connect) with a structured schema.
320
310
  # Run `exa-ai agent-run-create --help` to see every provider and when to use it:
321
- # fiber_ai, similarweb, baselayer, affiliate, particle_news, financial_datasets, jinko
311
+ # fiber, similarweb, baselayer, polymarket, macrobond, affiliate, particle,
312
+ # financial_datasets, jinko (up to 5 per run)
322
313
  exa-ai agent-run-create --wait \
323
314
  --query "Profile Anthropic: total funding and monthly web traffic" \
324
- --data-sources fiber_ai,similarweb \
315
+ --data-sources fiber,similarweb \
325
316
  --output-schema '{"type":"object","properties":{"name":{"type":"string"},"totalFunding":{"type":"string"},"monthlyVisits":{"type":"number"}}}'
326
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
+
327
322
  # Fetch an existing run
328
323
  exa-ai agent-run-get <run_id>
329
324
 
330
325
  # List recent runs
331
326
  exa-ai agent-run-list --limit 5
332
327
 
333
- # Cancel or delete a run
328
+ # Stop a run early and keep its results, or cancel or delete it
329
+ exa-ai agent-run-stop <run_id>
334
330
  exa-ai agent-run-cancel <run_id>
335
331
  exa-ai agent-run-delete <run_id>
336
332
 
337
- # Fetch a run's events
338
- 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>
339
387
  ```
340
388
 
341
389
  ## Error Handling
@@ -380,9 +428,6 @@ bundle exec rake test
380
428
 
381
429
  # Run integration tests (VCR-based, no real API calls)
382
430
  RUN_INTEGRATION_TESTS=true bundle exec rake test
383
-
384
- # Run CLI integration tests (real API calls, requires explicit opt-in)
385
- RUN_CLI_INTEGRATION_TESTS=true bundle exec rake test
386
431
  ```
387
432
 
388
433
  ### Integration Tests
@@ -395,20 +440,12 @@ RUN_CLI_INTEGRATION_TESTS=true bundle exec rake test
395
440
  - Set `RUN_INTEGRATION_TESTS=true` to run them
396
441
  - Safe to run during development
397
442
 
398
- **CLI integration tests (`RUN_CLI_INTEGRATION_TESTS`):**
399
- - Make real API calls through shell commands
400
- - Consume Exa's concurrent search quota
401
- - Set `RUN_CLI_INTEGRATION_TESTS=true` AND `EXA_API_KEY` to run them
402
- - **Warning:** Can exhaust API quota and trigger rate limits lasting 1-2 days
403
-
404
443
  **When to run integration tests:**
405
444
  - VCR tests: Anytime (safe, no real API calls)
406
- - CLI tests: Only before releases or when testing CLI-specific functionality
407
445
 
408
446
  **Test Coverage:**
409
447
  - **Unit tests** - Fast, no API calls, always run
410
448
  - **VCR integration tests** - Replay cassettes, skipped by default
411
- - **CLI integration tests** - Real API calls via shell, skipped by default
412
449
 
413
450
  ## Support
414
451
 
data/exe/exa-ai CHANGED
@@ -12,43 +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
- "research-start" => "Start a research task",
16
- "research-get" => "Get research task status",
17
- "research-list" => "List research tasks",
18
- "webset-create" => "Create a new webset",
19
- "webset-get" => "Get webset details",
20
- "webset-list" => "List websets",
21
- "webset-update" => "Update a webset",
22
- "webset-delete" => "Delete a webset",
23
- "webset-cancel" => "Cancel a webset",
24
- "webset-search-create" => "Create a search in a webset",
25
- "webset-search-get" => "Get webset search details",
26
- "webset-search-cancel" => "Cancel a webset search",
27
- "webset-item-list" => "List items in a webset",
28
- "webset-item-get" => "Get webset item details",
29
- "webset-item-delete" => "Delete a webset item",
30
- "enrichment-create" => "Create an enrichment",
31
- "enrichment-get" => "Get enrichment details",
32
- "enrichment-list" => "List enrichments",
33
- "enrichment-update" => "Update an enrichment",
34
- "enrichment-delete" => "Delete an enrichment",
35
- "enrichment-cancel" => "Cancel an enrichment",
36
- "import-create" => "Create a new import",
37
- "import-list" => "List imports",
38
- "import-get" => "Get import details",
39
- "import-update" => "Update an import",
40
- "import-delete" => "Delete an import",
41
- "monitor-create" => "Create a webset monitor",
42
- "monitor-get" => "Get monitor details",
43
- "monitor-list" => "List monitors",
44
- "monitor-update" => "Update a monitor",
45
- "monitor-delete" => "Delete a monitor",
46
- "monitor-runs-list" => "List monitor runs",
47
- "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",
48
24
  "agent-run-create" => "Create an agent run",
49
25
  "agent-run-get" => "Get agent run details",
50
26
  "agent-run-list" => "List agent runs",
51
27
  "agent-run-cancel" => "Cancel an agent run",
28
+ "agent-run-stop" => "Stop an agent run early and keep its results",
52
29
  "agent-run-delete" => "Delete an agent run",
53
30
  "agent-run-events" => "Get events for an agent run"
54
31
  }.freeze
@@ -74,72 +51,24 @@ module ExaCLI
74
51
  exec File.expand_path("../exa-ai-context", __FILE__), *ARGV[1..]
75
52
  when "get-contents"
76
53
  exec File.expand_path("../exa-ai-get-contents", __FILE__), *ARGV[1..]
77
- when "research-start"
78
- exec File.expand_path("../exa-ai-research-start", __FILE__), *ARGV[1..]
79
- when "research-get"
80
- exec File.expand_path("../exa-ai-research-get", __FILE__), *ARGV[1..]
81
- when "research-list"
82
- exec File.expand_path("../exa-ai-research-list", __FILE__), *ARGV[1..]
83
- when "webset-create"
84
- exec File.expand_path("../exa-ai-webset-create", __FILE__), *ARGV[1..]
85
- when "webset-get"
86
- exec File.expand_path("../exa-ai-webset-get", __FILE__), *ARGV[1..]
87
- when "webset-list"
88
- exec File.expand_path("../exa-ai-webset-list", __FILE__), *ARGV[1..]
89
- when "webset-update"
90
- exec File.expand_path("../exa-ai-webset-update", __FILE__), *ARGV[1..]
91
- when "webset-delete"
92
- exec File.expand_path("../exa-ai-webset-delete", __FILE__), *ARGV[1..]
93
- when "webset-cancel"
94
- exec File.expand_path("../exa-ai-webset-cancel", __FILE__), *ARGV[1..]
95
- when "webset-search-create"
96
- exec File.expand_path("../exa-ai-webset-search-create", __FILE__), *ARGV[1..]
97
- when "webset-search-get"
98
- exec File.expand_path("../exa-ai-webset-search-get", __FILE__), *ARGV[1..]
99
- when "webset-search-cancel"
100
- exec File.expand_path("../exa-ai-webset-search-cancel", __FILE__), *ARGV[1..]
101
- when "webset-item-list"
102
- exec File.expand_path("../exa-ai-webset-item-list", __FILE__), *ARGV[1..]
103
- when "webset-item-get"
104
- exec File.expand_path("../exa-ai-webset-item-get", __FILE__), *ARGV[1..]
105
- when "webset-item-delete"
106
- exec File.expand_path("../exa-ai-webset-item-delete", __FILE__), *ARGV[1..]
107
- when "enrichment-create"
108
- exec File.expand_path("../exa-ai-enrichment-create", __FILE__), *ARGV[1..]
109
- when "enrichment-get"
110
- exec File.expand_path("../exa-ai-enrichment-get", __FILE__), *ARGV[1..]
111
- when "enrichment-list"
112
- exec File.expand_path("../exa-ai-enrichment-list", __FILE__), *ARGV[1..]
113
- when "enrichment-update"
114
- exec File.expand_path("../exa-ai-enrichment-update", __FILE__), *ARGV[1..]
115
- when "enrichment-delete"
116
- exec File.expand_path("../exa-ai-enrichment-delete", __FILE__), *ARGV[1..]
117
- when "enrichment-cancel"
118
- exec File.expand_path("../exa-ai-enrichment-cancel", __FILE__), *ARGV[1..]
119
- when "import-create"
120
- exec File.expand_path("../exa-ai-import-create", __FILE__), *ARGV[1..]
121
- when "import-list"
122
- exec File.expand_path("../exa-ai-import-list", __FILE__), *ARGV[1..]
123
- when "import-get"
124
- exec File.expand_path("../exa-ai-import-get", __FILE__), *ARGV[1..]
125
- when "import-update"
126
- exec File.expand_path("../exa-ai-import-update", __FILE__), *ARGV[1..]
127
- when "import-delete"
128
- exec File.expand_path("../exa-ai-import-delete", __FILE__), *ARGV[1..]
129
- when "monitor-create"
130
- exec File.expand_path("../exa-ai-monitor-create", __FILE__), *ARGV[1..]
131
- when "monitor-get"
132
- exec File.expand_path("../exa-ai-monitor-get", __FILE__), *ARGV[1..]
133
- when "monitor-list"
134
- exec File.expand_path("../exa-ai-monitor-list", __FILE__), *ARGV[1..]
135
- when "monitor-update"
136
- exec File.expand_path("../exa-ai-monitor-update", __FILE__), *ARGV[1..]
137
- when "monitor-delete"
138
- exec File.expand_path("../exa-ai-monitor-delete", __FILE__), *ARGV[1..]
139
- when "monitor-runs-list"
140
- exec File.expand_path("../exa-ai-monitor-runs-list", __FILE__), *ARGV[1..]
141
- when "monitor-runs-get"
142
- 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..]
143
72
  when "agent-run-create"
144
73
  exec File.expand_path("../exa-ai-agent-run-create", __FILE__), *ARGV[1..]
145
74
  when "agent-run-get"
@@ -148,10 +77,15 @@ module ExaCLI
148
77
  exec File.expand_path("../exa-ai-agent-run-list", __FILE__), *ARGV[1..]
149
78
  when "agent-run-cancel"
150
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..]
151
82
  when "agent-run-delete"
152
83
  exec File.expand_path("../exa-ai-agent-run-delete", __FILE__), *ARGV[1..]
153
84
  when "agent-run-events"
154
85
  exec File.expand_path("../exa-ai-agent-run-events", __FILE__), *ARGV[1..]
86
+ when "research-start", "research-get", "research-list"
87
+ $stderr.puts "Error: Exa retired the Research API. Use 'exa-ai agent-run-create --query TEXT' instead."
88
+ exit 1
155
89
  else
156
90
  print_error_for_command(ARGV[0])
157
91
  exit 1
@@ -172,67 +106,26 @@ module ExaCLI
172
106
  ["get-contents", "Retrieve page contents"]
173
107
  ])
174
108
 
175
- print_command_section("Research", [
176
- ["research-start", "Start a research task"],
177
- ["research-get", "Get research task status"],
178
- ["research-list", "List research tasks"]
179
- ])
180
-
181
- print_command_section("Websets", [
182
- ["webset-create", "Create a new webset"],
183
- ["webset-get", "Get webset details"],
184
- ["webset-list", "List websets"],
185
- ["webset-update", "Update a webset"],
186
- ["webset-delete", "Delete a webset"],
187
- ["webset-cancel", "Cancel a webset"]
188
- ])
189
-
190
- print_command_section("Webset Searches", [
191
- ["webset-search-create", "Create a search in a webset"],
192
- ["webset-search-get", "Get webset search details"],
193
- ["webset-search-cancel", "Cancel a webset search"]
194
- ])
195
-
196
- print_command_section("Webset Items", [
197
- ["webset-item-list", "List items in a webset"],
198
- ["webset-item-get", "Get webset item details"],
199
- ["webset-item-delete", "Delete a webset item"]
200
- ])
201
-
202
- print_command_section("Webset Enrichments", [
203
- ["enrichment-create", "Create an enrichment"],
204
- ["enrichment-get", "Get enrichment details"],
205
- ["enrichment-list", "List enrichments"],
206
- ["enrichment-update", "Update an enrichment"],
207
- ["enrichment-delete", "Delete an enrichment"],
208
- ["enrichment-cancel", "Cancel an enrichment"]
209
- ])
210
-
211
- print_command_section("Imports", [
212
- ["import-create", "Create a new import"],
213
- ["import-list", "List imports"],
214
- ["import-get", "Get import details"],
215
- ["import-update", "Update an import"],
216
- ["import-delete", "Delete an import"]
217
- ])
218
-
219
109
  print_command_section("Agent Runs", [
220
110
  ["agent-run-create", "Create an agent run"],
221
111
  ["agent-run-get", "Get agent run details"],
222
112
  ["agent-run-list", "List agent runs"],
223
113
  ["agent-run-cancel", "Cancel an agent run"],
114
+ ["agent-run-stop", "Stop an agent run early and keep its results"],
224
115
  ["agent-run-delete", "Delete an agent run"],
225
116
  ["agent-run-events", "Get events for an agent run"]
226
117
  ])
227
118
 
228
- print_command_section("Webset Monitors", [
229
- ["monitor-create", "Create a webset monitor"],
230
- ["monitor-get", "Get monitor details"],
231
- ["monitor-list", "List monitors"],
232
- ["monitor-update", "Update a monitor"],
233
- ["monitor-delete", "Delete a monitor"],
234
- ["monitor-runs-list", "List monitor runs"],
235
- ["monitor-runs-get", "Get monitor run details"]
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"]
236
129
  ])
237
130
 
238
131
  puts "Global Options:"
@@ -242,7 +135,7 @@ module ExaCLI
242
135
  puts "Examples:"
243
136
  puts " exa-ai search 'ruby programming'"
244
137
  puts " exa-ai context 'React hooks' --tokens-num 5000"
245
- puts " exa-ai research-start --instructions 'Find AI papers'"
138
+ puts " exa-ai agent-run-create --query 'Find AI papers'"
246
139
  end
247
140
 
248
141
  def self.print_command_section(title, commands)