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:



256
257
258
 
# File 'lib/exa/client.rb', line 256

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:



183
184
185
 
# File 'lib/exa/client.rb', line 183

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:



292
293
294
 
# File 'lib/exa/client.rb', line 292

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:



215
216
217
 
# File 'lib/exa/client.rb', line 215

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:



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

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:



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

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:



202
203
204
 
# File 'lib/exa/client.rb', line 202

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:



274
275
276
 
# File 'lib/exa/client.rb', line 274

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:



247
248
249
 
# File 'lib/exa/client.rb', line 247

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:



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

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



310
311
312
 
# File 'lib/exa/client.rb', line 310

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:



435
436
437
 
# File 'lib/exa/client.rb', line 435

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:



175
176
177
 
# File 'lib/exa/client.rb', line 175

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:



224
225
226
 
# File 'lib/exa/client.rb', line 224

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:



366
367
368
 
# File 'lib/exa/client.rb', line 366

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



301
302
303
 
# File 'lib/exa/client.rb', line 301

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:



415
416
417
 
# File 'lib/exa/client.rb', line 415

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:



455
456
457
 
# File 'lib/exa/client.rb', line 455

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:



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

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:



283
284
285
 
# File 'lib/exa/client.rb', line 283

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

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

Search for LinkedIn company pages

Convenience method that restricts search to LinkedIn company profiles using keyword search for precise name matching.

Parameters:

  • query (String) —

    Company name to search

  • params (Hash) —

    Additional search parameters

Options Hash (**params):

  • :numResults (Integer) —

    Number of results to return

Returns:



134
135
136
 
# File 'lib/exa/client.rb', line 134

def linkedin_company(query, **params)
  search(query, type: "keyword", includeDomains: ["linkedin.com/company"], **params)
end

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

Search for LinkedIn profiles

Convenience method that restricts search to LinkedIn individual profiles using keyword search for precise name matching.

Parameters:

  • query (String) —

    Person name to search

  • params (Hash) —

    Additional search parameters

Options Hash (**params):

  • :numResults (Integer) —

    Number of results to return

Returns:



147
148
149
 
# File 'lib/exa/client.rb', line 147

def linkedin_person(query, **params)
  search(query, type: "keyword", includeDomains: ["linkedin.com/in"], **params)
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:



328
329
330
 
# File 'lib/exa/client.rb', line 328

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

#list_items(webset_id:) ⇒ Array<Hash>

List all items in a webset

Parameters:

  • webset_id (String) —

    Webset ID

Returns:

  • (Array<Hash>) —

    Array of items



318
319
320
 
# File 'lib/exa/client.rb', line 318

def list_items(webset_id:)
  Services::Websets::ListItems.new(connection, webset_id: webset_id).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:



446
447
448
 
# File 'lib/exa/client.rb', line 446

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:



407
408
409
 
# File 'lib/exa/client.rb', line 407

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:



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

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:



238
239
240
 
# File 'lib/exa/client.rb', line 238

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:



377
378
379
 
# File 'lib/exa/client.rb', line 377

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:



427
428
429
 
# File 'lib/exa/client.rb', line 427

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 metadata

Parameters:

  • id (String) —

    Webset ID

  • params (Hash) —

    Update parameters

Options Hash (**params):

  • :metadata (Hash) —

    Metadata to update

Returns:



193
194
195
 
# File 'lib/exa/client.rb', line 193

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:



358
359
360
 
# File 'lib/exa/client.rb', line 358

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