Class: Exa::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/exa/client.rb

Overview

Main client for interacting with the Exa.ai API

Provides methods for all supported Exa.ai operations including search, content retrieval, answer generation, and async research tasks.

Examples:

Basic usage

client = Exa::Client.new(api_key: "your-key")
results = client.search("ruby on rails")
results.results.each { |r| puts r.title }

Using configuration

Exa.configure { |config| config.api_key = "your-key" }
client = Exa::Client.new

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, **options) ⇒ Client

Initialize a new Exa client

Parameters:

  • api_key (String, nil) (defaults to: nil) —

    API key for authentication. Falls back to Exa.api_key if not provided

  • options (Hash) —

    Connection options

Options Hash (**options):

  • :base_url (String) —

    Custom API base URL (default: https://api.exa.ai)

  • :timeout (Integer) —

    Request timeout in seconds (default: 30)

Raises:



25
26
27
28
29
30
 
# File 'lib/exa/client.rb', line 25

def initialize(api_key: nil, **options)
  @api_key = api_key || Exa.api_key
  @options = options

  validate_api_key!
end

Instance Method Details

#agent_run_cancel(run_id) ⇒ Resources::AgentRun

Cancel an in-progress agent run

Parameters:

  • run_id (String) —

    Agent run ID

Returns:



169
170
171
 
# File 'lib/exa/client.rb', line 169

def agent_run_cancel(run_id)
  Services::AgentRunCancel.new(connection, run_id: run_id).call
end

#agent_run_create(query:, **params) ⇒ Resources::AgentRun

Create a new agent run

Parameters:

  • query (String) —

    The query or task for the agent to execute (required)

  • params (Hash) —

    Additional run parameters

Options Hash (**params):

  • :input (Hash) —

    Input data for the agent run. Multi-word keys inside input, data_sources items, and metadata must be supplied in the exact shape the API expects — the parameter converter does not recurse into nested values (same contract as output_schema).

  • :data_sources (Array<Hash>) —

    Data sources for the agent run

  • :metadata (Hash) —

    Custom metadata

Returns:



126
127
128
 
# File 'lib/exa/client.rb', line 126

def agent_run_create(query:, **params)
  Services::AgentRunCreate.new(connection, query: query, **params).call
end

#agent_run_delete(run_id) ⇒ Resources::AgentRun

Delete an agent run

Parameters:

  • run_id (String) —

    Agent run ID

Returns:



177
178
179
 
# File 'lib/exa/client.rb', line 177

def agent_run_delete(run_id)
  Services::AgentRunDelete.new(connection, run_id: run_id).call
end

#agent_run_events(run_id, **params) ⇒ Array<Hash>

List events for an agent run

Parameters:

  • run_id (String) —

    Agent run ID

  • params (Hash) —

    Listing parameters

Options Hash (**params):

  • :limit (Integer) —

    Maximum number of events to return

  • :cursor (String) —

    Cursor for pagination

Returns:

  • (Array<Hash>) —

    List of agent run events



188
189
190
 
# File 'lib/exa/client.rb', line 188

def agent_run_events(run_id, **params)
  Services::AgentRunEvents.new(connection, run_id: run_id, **params).call
end

#agent_run_get(run_id) ⇒ Resources::AgentRun

Get the status and results of an agent run

Parameters:

  • run_id (String) —

    Agent run ID

Returns:



151
152
153
 
# File 'lib/exa/client.rb', line 151

def agent_run_get(run_id)
  Services::AgentRunGet.new(connection, run_id: run_id).call
end

#agent_run_list(**params) ⇒ Resources::AgentRunList

List all agent runs

Parameters:

  • params (Hash) —

    Listing parameters

Options Hash (**params):

  • :limit (Integer) —

    Maximum number of runs to return

  • :cursor (String) —

    Cursor for pagination

Returns:



161
162
163
 
# File 'lib/exa/client.rb', line 161

def agent_run_list(**params)
  Services::AgentRunList.new(connection, **params).call
end

#agent_run_stream(query:, **params) {|chunk| ... } ⇒ void

This method returns an undefined value.

Stream an agent run, yielding chunks as they arrive

Parameters:

  • query (String) —

    The query or task for the agent to execute (required)

  • params (Hash) —

    Additional run parameters

Options Hash (**params):

  • :input (Hash) —

    Input data for the agent run. Multi-word keys inside input, data_sources items, and metadata must be supplied in the exact shape the API expects — the parameter converter does not recurse into nested values (same contract as output_schema).

  • :data_sources (Array<Hash>) —

    Data sources for the agent run

  • :metadata (Hash) —

    Custom metadata

Yields:

  • (chunk) —

    Yields each streamed event chunk as it arrives

Yield Parameters:

  • chunk (Hash) —

    Partial agent run event data



143
144
145
 
# File 'lib/exa/client.rb', line 143

def agent_run_stream(query:, **params, &block)
  Services::AgentRunStream.new(connection, query: query, **params).call(&block)
end

#answer(query, **options) ⇒ Resources::Answer

Get AI-generated answers to a query

Parameters:

  • query (String) —

    Question or query

  • options (Hash) —

    Answer options

Options Hash (**options):

  • :format (String) —

    Response format (default: standard)

Returns:



70
71
72
 
# File 'lib/exa/client.rb', line 70

def answer(query, **options)
  Services::Answer.new(connection, query: query, **options).call
end

#answer_stream(query, **options) {|chunk| ... } ⇒ void

This method returns an undefined value.

Stream AI-generated answers to a query

Returns partial answer chunks as they are generated by the API.

Parameters:

  • query (String) —

    Question or query

  • options (Hash) —

    Answer options

Options Hash (**options):

  • :text (Boolean) —

    Include full text content (default: false)

  • :output_schema (Hash) —

    JSON schema for structured output

Yields:

  • (chunk) —

    Yields each answer chunk as it arrives

Yield Parameters:

  • chunk (Hash) —

    Partial answer data with => "text"



85
86
87
 
# File 'lib/exa/client.rb', line 85

def answer_stream(query, **options, &block)
  Services::AnswerStream.new(connection, query: query, **options).call(&block)
end

#cancel_enrichment(webset_id:, id:) ⇒ Resources::WebsetEnrichment

Cancel a running enrichment

Parameters:

  • webset_id (String) —

    Webset ID

  • id (String) —

    Enrichment ID

Returns:



308
309
310
 
# File 'lib/exa/client.rb', line 308

def cancel_enrichment(webset_id:, id:)
  Services::Websets::CancelEnrichment.new(connection, webset_id: webset_id, id: id).call
end

#cancel_webset(id) ⇒ Resources::Webset

Cancel in-progress operations on a webset

Parameters:

  • id (String) —

    Webset ID

Returns:



234
235
236
 
# File 'lib/exa/client.rb', line 234

def cancel_webset(id)
  Services::Websets::Cancel.new(connection, id: id).call
end

#cancel_webset_search(webset_id:, id:) ⇒ Resources::WebsetSearch

Cancel a webset search

Parameters:

  • webset_id (String) —

    Webset ID

  • id (String) —

    Search ID

Returns:



344
345
346
 
# File 'lib/exa/client.rb', line 344

def cancel_webset_search(webset_id:, id:)
  Services::Websets::CancelSearch.new(connection, webset_id: webset_id, id: id).call
end

#context(query, **params) ⇒ Resources::SearchResult

Search code repositories

Parameters:

  • query (String) —

    Code search query

  • params (Hash) —

    Search parameters

Options Hash (**params):

  • :languages (Array<String>) —

    Programming languages to search

Returns:



198
199
200
 
# File 'lib/exa/client.rb', line 198

def context(query, **params)
  Services::Context.new(connection, query: query, **params).call
end

#create_enrichment(webset_id:, **params) ⇒ Resources::WebsetEnrichment

Create a new enrichment for a webset

Parameters:

  • webset_id (String) —

    Webset ID

  • params (Hash) —

    Enrichment parameters

Options Hash (**params):

  • :description (String) —

    Description of data to extract

  • :format (String) —

    Format type (text, url, options, etc.)

  • :options (Array<Hash>) —

    Options for enrichment

  • :metadata (Hash) —

    Custom metadata

Returns:



267
268
269
 
# File 'lib/exa/client.rb', line 267

def create_enrichment(webset_id:, **params)
  Services::Websets::CreateEnrichment.new(connection, webset_id: webset_id, **params).call
end

#create_import(**params) ⇒ Resources::Import

Create a new import

Parameters:

  • params (Hash) —

    Import parameters

Options Hash (**params):

  • :size (Integer) —

    Size of the import file

  • :count (Integer) —

    Number of items to import

  • :title (String) —

    Import title

  • :format (String) —

    Import format (e.g., "csv")

  • :entity (Hash) —

    Entity type specification

  • :metadata (Hash) —

    Custom metadata

  • :csv (Hash) —

    CSV-specific configuration

Returns:



398
399
400
 
# File 'lib/exa/client.rb', line 398

def create_import(**params)
  Services::Websets::CreateImport.new(connection, **params).call
end

#create_monitor(webset_id:, cadence:, behavior:, **params) ⇒ Resources::Monitor

Create a new monitor for a webset

Parameters:

  • webset_id (String) —

    Webset ID

  • cadence (Hash) —

    Schedule configuration with :cron and :timezone

  • behavior (Hash) —

    Behavior configuration (type, query, etc.)

  • params (Hash) —

    Additional monitor parameters

Options Hash (**params):

  • :metadata (Hash) —

    Custom metadata

Returns:



452
453
454
 
# File 'lib/exa/client.rb', line 452

def create_monitor(webset_id:, cadence:, behavior:, **params)
  Services::Websets::Monitors::Create.new(connection, webset_id: webset_id, cadence: cadence, behavior: behavior, **params).call
end

#create_webset(**params) ⇒ Resources::Webset

Create a new webset

Parameters:

  • params (Hash) —

    Creation parameters

Options Hash (**params):

  • :search (Hash) —

    Search configuration

Returns:



254
255
256
 
# File 'lib/exa/client.rb', line 254

def create_webset(**params)
  Services::Websets::Create.new(connection, **params).call
end

#create_webset_search(webset_id:, **params) ⇒ Resources::WebsetSearch

Create a new search within a webset

Parameters:

  • webset_id (String) —

    Webset ID

  • params (Hash) —

    Search parameters

Options Hash (**params):

  • :query (String) —

    The search query (required)

  • :count (Integer) —

    Number of results to find

  • :entity (Hash) —

    Entity type specification

  • :criteria (Array<Hash>) —

    Search criteria

  • :exclude (Array<Hash>) —

    Items to exclude from results

  • :scope (Array<Hash>) —

    Limit search to specific sources

  • :recall (Boolean) —

    Whether to estimate total available results

  • :behavior (String) —

    "override" or "append" (default: "override")

  • :metadata (Hash) —

    Custom metadata

Returns:



326
327
328
 
# File 'lib/exa/client.rb', line 326

def create_webset_search(webset_id:, **params)
  Services::Websets::CreateSearch.new(connection, webset_id: webset_id, **params).call
end

#delete_enrichment(webset_id:, id:) ⇒ Resources::WebsetEnrichment

Delete an enrichment

Parameters:

  • webset_id (String) —

    Webset ID

  • id (String) —

    Enrichment ID

Returns:



299
300
301
 
# File 'lib/exa/client.rb', line 299

def delete_enrichment(webset_id:, id:)
  Services::Websets::DeleteEnrichment.new(connection, webset_id: webset_id, id: id).call
end

#delete_import(id) ⇒ Resources::Import

Delete an import

Parameters:

  • id (String) —

    Import ID

Returns:



440
441
442
 
# File 'lib/exa/client.rb', line 440

def delete_import(id)
  Services::Websets::DeleteImport.new(connection, id: id).call
end

#delete_item(webset_id:, id:) ⇒ Boolean

Delete a webset item by ID

Parameters:

  • webset_id (String) —

    Webset ID

  • id (String) —

    Item ID

Returns:

  • (Boolean) —

    True if deletion was successful



362
363
364
 
# File 'lib/exa/client.rb', line 362

def delete_item(webset_id:, id:)
  Services::Websets::DeleteItem.new(connection, webset_id: webset_id, id: id).call
end

#delete_monitor(id:) ⇒ Resources::Monitor

Delete a monitor

Parameters:

  • id (String) —

    Monitor ID

Returns:



490
491
492
 
# File 'lib/exa/client.rb', line 490

def delete_monitor(id:)
  Services::Websets::Monitors::Delete.new(connection, id: id).call
end

#delete_webset(id) ⇒ Resources::Webset

Delete a webset

Parameters:

  • id (String) —

    Webset ID

Returns:



226
227
228
 
# File 'lib/exa/client.rb', line 226

def delete_webset(id)
  Services::Websets::Delete.new(connection, id: id).call
end

#find_similar(url, **options) ⇒ Resources::SearchResult

Find similar content to a given URL

Parameters:

  • url (String) —

    URL to find similar content for

  • options (Hash) —

    Search options

Options Hash (**options):

  • :num_results (Integer) —

    Number of results to return

Returns:



51
52
53
 
# File 'lib/exa/client.rb', line 51

def find_similar(url, **options)
  Services::FindSimilar.new(connection, url: url, **options).call
end

#get_contents(urls, **options) ⇒ Resources::ContentCollection

Get full page contents for URLs

Parameters:

  • urls (Array<String>, String) —

    URL or URLs to fetch contents for

  • options (Hash) —

    Fetch options

Returns:

  • (Resources::ContentCollection) —

    Collection of page contents



60
61
62
 
# File 'lib/exa/client.rb', line 60

def get_contents(urls, **options)
  Services::GetContents.new(connection, urls: urls, **options).call
end

#get_enrichment(webset_id:, id:) ⇒ Resources::WebsetEnrichment

Get a specific enrichment by ID

Parameters:

  • webset_id (String) —

    Webset ID

  • id (String) —

    Enrichment ID

Returns:



276
277
278
 
# File 'lib/exa/client.rb', line 276

def get_enrichment(webset_id:, id:)
  Services::Websets::RetrieveEnrichment.new(connection, webset_id: webset_id, id: id).call
end

#get_import(id) ⇒ Resources::Import

Get a specific import by ID

Parameters:

  • id (String) —

    Import ID

Returns:



421
422
423
 
# File 'lib/exa/client.rb', line 421

def get_import(id)
  Services::Websets::GetImport.new(connection, id: id).call
end

#get_item(webset_id:, id:) ⇒ Hash

Get a webset item by ID

Parameters:

  • webset_id (String) —

    Webset ID

  • id (String) —

    Item ID

Returns:

  • (Hash) —

    The requested item



353
354
355
 
# File 'lib/exa/client.rb', line 353

def get_item(webset_id:, id:)
  Services::Websets::GetItem.new(connection, webset_id: webset_id, id: id).call
end

#get_monitor(id:) ⇒ Resources::Monitor

Get a specific monitor by ID

Parameters:

  • id (String) —

    Monitor ID

Returns:



470
471
472
 
# File 'lib/exa/client.rb', line 470

def get_monitor(id:)
  Services::Websets::Monitors::Get.new(connection, id: id).call
end

#get_monitor_run(monitor_id:, id:) ⇒ Resources::MonitorRun

Get a specific monitor run by ID

Parameters:

  • monitor_id (String) —

    Monitor ID

  • id (String) —

    Run ID

Returns:



510
511
512
 
# File 'lib/exa/client.rb', line 510

def get_monitor_run(monitor_id:, id:)
  Services::Websets::Monitors::Runs::Get.new(connection, monitor_id: monitor_id, id: id).call
end

#get_webset(id, **params) ⇒ Resources::Webset

Get a specific webset by ID

Parameters:

  • id (String) —

    Webset ID

  • params (Hash) —

    Optional parameters

Options Hash (**params):

  • :expand (Array<String>) —

    Resources to expand in response (e.g., ['items'])

Returns:



218
219
220
 
# File 'lib/exa/client.rb', line 218

def get_webset(id, **params)
  Services::Websets::Retrieve.new(connection, id: id, **params).call
end

#get_webset_search(webset_id:, id:) ⇒ Resources::WebsetSearch

Get a webset search by ID

Parameters:

  • webset_id (String) —

    Webset ID

  • id (String) —

    Search ID

Returns:



335
336
337
 
# File 'lib/exa/client.rb', line 335

def get_webset_search(webset_id:, id:)
  Services::Websets::GetSearch.new(connection, webset_id: webset_id, id: id).call
end

#list_imports(**params) ⇒ Resources::ImportCollection

List all imports

Parameters:

  • params (Hash) —

    Pagination parameters

Options Hash (**params):

  • :cursor (String) —

    Cursor for pagination

  • :limit (Integer) —

    Maximum number of imports to return

Returns:



383
384
385
 
# File 'lib/exa/client.rb', line 383

def list_imports(**params)
  Services::Websets::ListImports.new(connection, **params).call
end

#list_items(webset_id:, **params) ⇒ Resources::WebsetItemCollection

List all items in a webset

Parameters:

  • webset_id (String) —

    Webset ID

  • params (Hash) —

    Pagination parameters

Options Hash (**params):

  • :cursor (String) —

    Cursor for pagination

  • :limit (Integer) —

    Maximum number of items to return (default: 20)

Returns:



373
374
375
 
# File 'lib/exa/client.rb', line 373

def list_items(webset_id:, **params)
  Services::Websets::ListItems.new(connection, webset_id: webset_id, **params).call
end

#list_monitor_runs(monitor_id:, **params) ⇒ Resources::MonitorRunCollection

List all runs for a specific monitor

Parameters:

  • monitor_id (String) —

    Monitor ID

  • params (Hash) —

    Pagination parameters

Options Hash (**params):

  • :cursor (String) —

    Cursor for pagination

  • :limit (Integer) —

    Maximum number of runs to return

Returns:



501
502
503
 
# File 'lib/exa/client.rb', line 501

def list_monitor_runs(monitor_id:, **params)
  Services::Websets::Monitors::Runs::List.new(connection, monitor_id: monitor_id, **params).call
end

#list_monitors(**params) ⇒ Resources::MonitorCollection

List all monitors

Parameters:

  • params (Hash) —

    Pagination parameters

Options Hash (**params):

  • :cursor (String) —

    Cursor for pagination

  • :limit (Integer) —

    Maximum number of monitors to return

Returns:



462
463
464
 
# File 'lib/exa/client.rb', line 462

def list_monitors(**params)
  Services::Websets::Monitors::List.new(connection, **params).call
end

#list_websets(**params) ⇒ Resources::WebsetCollection

List all websets

Parameters:

  • params (Hash) —

    Pagination parameters

Options Hash (**params):

  • :cursor (String) —

    Cursor for pagination

  • :limit (Integer) —

    Maximum number of websets to return

Returns:



208
209
210
 
# File 'lib/exa/client.rb', line 208

def list_websets(**params)
  Services::Websets::List.new(connection, **params).call
end

#research_get(research_id, **params) ⇒ Resources::Research

Get status and results of a research task

Parameters:

  • research_id (String) —

    Research task ID

  • params (Hash) —

    Fetch options

Returns:

  • (Resources::Research) —

    Research task with current status and results



111
112
113
 
# File 'lib/exa/client.rb', line 111

def research_get(research_id, **params)
  Services::ResearchGet.new(connection, research_id: research_id, **params).call
end

#research_list(**params) ⇒ Resources::ResearchList

List all research tasks

Parameters:

  • params (Hash) —

    Listing parameters

Options Hash (**params):

  • :limit (Integer) —

    Maximum number of tasks to return

Returns:



102
103
104
 
# File 'lib/exa/client.rb', line 102

def research_list(**params)
  Services::ResearchList.new(connection, **params).call
end

#research_start(**params) ⇒ Resources::Research

Start an asynchronous research task

Parameters:

  • params (Hash) —

    Research parameters

Returns:

  • (Resources::Research) —

    Research task with ID



93
94
95
 
# File 'lib/exa/client.rb', line 93

def research_start(**params)
  Services::ResearchStart.new(connection, **params).call
end

#search(query, **params) ⇒ Resources::SearchResult

Execute a search query

Parameters:

  • query (String) —

    Search query

  • params (Hash) —

    Additional search parameters

Options Hash (**params):

  • :type (String) —

    Search type (web, news, etc.)

  • :include_domains (Array<String>) —

    Domains to include in results

  • :exclude_domains (Array<String>) —

    Domains to exclude from results

  • :num_results (Integer) —

    Number of results to return

Returns:



41
42
43
 
# File 'lib/exa/client.rb', line 41

def search(query, **params)
  Services::Search.new(connection, query: query, **params).call
end

#update_enrichment(webset_id:, id:, **params) ⇒ Resources::WebsetEnrichment

Update an enrichment

Parameters:

  • webset_id (String) —

    Webset ID

  • id (String) —

    Enrichment ID

  • params (Hash) —

    Update parameters

Options Hash (**params):

  • :description (String) —

    Updated description

  • :format (String) —

    Updated format

  • :options (Array<Hash>) —

    Updated options

  • :metadata (Hash) —

    Updated metadata

Returns:



290
291
292
 
# File 'lib/exa/client.rb', line 290

def update_enrichment(webset_id:, id:, **params)
  Services::Websets::UpdateEnrichment.new(connection, webset_id: webset_id, id: id, **params).call
end

#update_import(id, **params) ⇒ Resources::Import

Update an import

Parameters:

  • id (String) —

    Import ID

  • params (Hash) —

    Update parameters

Options Hash (**params):

  • :title (String) —

    Updated title

  • :metadata (Hash) —

    Updated metadata

Returns:



432
433
434
 
# File 'lib/exa/client.rb', line 432

def update_import(id, **params)
  Services::Websets::UpdateImport.new(connection, id: id, **params).call
end

#update_monitor(id:, **params) ⇒ Resources::Monitor

Update a monitor

Parameters:

  • id (String) —

    Monitor ID

  • params (Hash) —

    Update parameters

Options Hash (**params):

  • :cadence (Hash) —

    Updated schedule configuration

  • :behavior (Hash) —

    Updated behavior configuration

  • :metadata (Hash) —

    Updated metadata

Returns:



482
483
484
 
# File 'lib/exa/client.rb', line 482

def update_monitor(id:, **params)
  Services::Websets::Monitors::Update.new(connection, id: id, **params).call
end

#update_webset(id, **params) ⇒ Resources::Webset

Update a webset's title and/or metadata

Parameters:

  • id (String) —

    Webset ID

  • params (Hash) —

    Update parameters

Options Hash (**params):

  • :title (String) —

    Title for the webset

  • :metadata (Hash) —

    Metadata to update

Returns:



245
246
247
 
# File 'lib/exa/client.rb', line 245

def update_webset(id, **params)
  Services::Websets::Update.new(connection, id: id, **params).call
end

#upload_import(file_path:, **params) ⇒ Resources::Import

Upload a file for import (creates import and uploads file)

Parameters:

  • file_path (String) —

    Path to the file to upload

  • params (Hash) —

    Import parameters

Options Hash (**params):

  • :count (Integer) —

    Number of items to import

  • :title (String) —

    Import title

  • :format (String) —

    Import format (e.g., "csv")

  • :entity (Hash) —

    Entity type specification

  • :metadata (Hash) —

    Custom metadata

  • :csv (Hash) —

    CSV-specific configuration

Returns:



413
414
415
 
# File 'lib/exa/client.rb', line 413

def upload_import(file_path:, **params)
  Services::Websets::UploadImport.new(connection, file_path: file_path, **params).call
end