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: 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

#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:



231
232
233
 
# File 'lib/exa/client.rb', line 231

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:



157
158
159
 
# File 'lib/exa/client.rb', line 157

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:



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

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:



121
122
123
 
# File 'lib/exa/client.rb', line 121

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:



190
191
192
 
# File 'lib/exa/client.rb', line 190

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:



321
322
323
 
# File 'lib/exa/client.rb', line 321

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:



375
376
377
 
# File 'lib/exa/client.rb', line 375

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:



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

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:



249
250
251
 
# File 'lib/exa/client.rb', line 249

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:



222
223
224
 
# File 'lib/exa/client.rb', line 222

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:



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

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



285
286
287
 
# File 'lib/exa/client.rb', line 285

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:



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

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:



149
150
151
 
# File 'lib/exa/client.rb', line 149

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:



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

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:



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

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



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

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:



393
394
395
 
# File 'lib/exa/client.rb', line 393

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:



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

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:



141
142
143
 
# File 'lib/exa/client.rb', line 141

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:



258
259
260
 
# File 'lib/exa/client.rb', line 258

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:



306
307
308
 
# File 'lib/exa/client.rb', line 306

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:



296
297
298
 
# File 'lib/exa/client.rb', line 296

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:



424
425
426
 
# File 'lib/exa/client.rb', line 424

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:



385
386
387
 
# File 'lib/exa/client.rb', line 385

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:



131
132
133
 
# File 'lib/exa/client.rb', line 131

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:



213
214
215
 
# File 'lib/exa/client.rb', line 213

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:



355
356
357
 
# File 'lib/exa/client.rb', line 355

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:



405
406
407
 
# File 'lib/exa/client.rb', line 405

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:



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

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:



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

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