exa-js 2.19.0 → 2.22.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.
package/README.md CHANGED
@@ -120,7 +120,7 @@ for await (const chunk of exa.streamAnswer("Explain quantum computing")) {
120
120
  }
121
121
  ```
122
122
 
123
- ## Web Search tools
123
+ ## Web Search and Contents tools
124
124
 
125
125
  Use Exa as a `web_search` tool in an OpenAI or Anthropic loop. Call `webSearch()` with no arguments to get Exa's recommended settings for agentic search (`type: "auto"` and `contents: { highlights: true }`).
126
126
 
@@ -171,6 +171,19 @@ const response = await anthropic.messages.create({
171
171
  });
172
172
  ```
173
173
 
174
+ `getContents()` is available in the same namespaces and lets the model read pages it already has URLs for. It takes a list of URLs and accepts every `exa.getContents` option:
175
+
176
+ ```ts
177
+ const completion = await openai.chat.completions.create({
178
+ model: "gpt-5.6",
179
+ messages,
180
+ tools: [
181
+ exa.openai.webSearch(),
182
+ exa.openai.getContents({ summary: true, livecrawl: "preferred" }),
183
+ ],
184
+ });
185
+ ```
186
+
174
187
  ## Agent API
175
188
 
176
189
  ```ts
package/dist/index.d.mts CHANGED
@@ -3989,16 +3989,38 @@ type WebSearchToolConfig = RegularSearchOptions & {
3989
3989
  /** Tool description shown to the model. */
3990
3990
  description?: string;
3991
3991
  };
3992
+ type GetContentsToolConfig = ContentsOptions & {
3993
+ /**
3994
+ * Tool name shown to the model. Defaults to `"get_contents"`. Set a custom
3995
+ * name to avoid collisions, or to register multiple differently-configured
3996
+ * contents tools.
3997
+ */
3998
+ name?: string;
3999
+ /** Tool description shown to the model. */
4000
+ description?: string;
4001
+ };
3992
4002
  type ToolNamespace = {
3993
4003
  webSearch(config?: WebSearchToolConfig): WebSearchTool;
4004
+ getContents(config?: GetContentsToolConfig): GetContentsTool;
3994
4005
  };
3995
4006
  type SearchArgs = {
3996
4007
  query: string;
3997
4008
  };
4009
+ type GetContentsArgs = {
4010
+ urls: string[];
4011
+ };
3998
4012
  type WebSearchTool = ExaToolSpec<SearchArgs, SearchResponse<ContentsOptions>>;
4013
+ type GetContentsTool = ExaToolSpec<GetContentsArgs, SearchResponse<ContentsOptions>>;
3999
4014
  declare const DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
4015
+ declare const DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION = "Read the full contents of web pages you already have URLs for, such as pages returned by a search or mentioned by the user.";
4000
4016
  /** Create a `web_search` tool. Defaults to `type: "auto"` and highlights. */
4001
4017
  declare function createWebSearchTool(exa: Exa, registry: ToolRegistry, config?: WebSearchToolConfig): WebSearchTool;
4018
+ /**
4019
+ * Create a `get_contents` tool that reads pages the model already has URLs for.
4020
+ * Inherits `exa.getContents` defaults, which return page text when no content
4021
+ * option is configured.
4022
+ */
4023
+ declare function createGetContentsTool(exa: Exa, registry: ToolRegistry, config?: GetContentsToolConfig): GetContentsTool;
4002
4024
  declare class ToolRegistry {
4003
4025
  private readonly registry;
4004
4026
  register(tool: ExaToolSpec): void;
@@ -4030,6 +4052,8 @@ declare class AnthropicTools {
4030
4052
  constructor(exa: Exa, registry: ToolRegistry);
4031
4053
  /** Anthropic `web_search` tool. Defaults to `auto` + highlights. */
4032
4054
  webSearch(config?: WebSearchToolConfig): AnthropicRunnable;
4055
+ /** Anthropic `get_contents` tool for reading pages by URL. */
4056
+ getContents(config?: GetContentsToolConfig): AnthropicRunnable;
4033
4057
  /**
4034
4058
  * Run the `tool_use` blocks in an assistant message and return the matching
4035
4059
  * `tool_result` blocks. Every `tool_use` block is answered so the follow-up
@@ -4099,6 +4123,8 @@ declare class OpenAIResponsesTools {
4099
4123
  }) => Promise<ResponsesFunctionCallOutput[]>);
4100
4124
  /** Responses API `web_search` tool. Defaults to `auto` + highlights. */
4101
4125
  webSearch(config?: WebSearchToolConfig): OpenAIResponsesRunnable;
4126
+ /** Responses API `get_contents` tool for reading pages by URL. */
4127
+ getContents(config?: GetContentsToolConfig): OpenAIResponsesRunnable;
4102
4128
  /**
4103
4129
  * Run the function calls in a Responses API response (or output item array)
4104
4130
  * and return `function_call_output` items. Every function call is answered
@@ -4118,6 +4144,8 @@ declare class OpenAITools {
4118
4144
  constructor(exa: Exa, registry: ToolRegistry);
4119
4145
  /** Chat Completions `web_search` tool. Defaults to `auto` + highlights. */
4120
4146
  webSearch(config?: WebSearchToolConfig): OpenAIRunnable;
4147
+ /** Chat Completions `get_contents` tool for reading pages by URL. */
4148
+ getContents(config?: GetContentsToolConfig): OpenAIRunnable;
4121
4149
  /**
4122
4150
  * Run the tool calls in a Chat Completions assistant message and return the
4123
4151
  * matching `role: "tool"` messages. Every tool call is answered so the
@@ -4219,6 +4247,8 @@ declare class ExaError extends Error {
4219
4247
  constructor(message: string, statusCode: number, timestamp?: string, path?: string, envelope?: ExaErrorEnvelope);
4220
4248
  }
4221
4249
 
4250
+ /** Exa-Beta token required for Dynamic Highlights (research preview). */
4251
+ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
4222
4252
  /**
4223
4253
  * Options for retrieving page contents
4224
4254
  * @typedef {Object} ContentsOptions
@@ -4227,6 +4257,7 @@ declare class ExaError extends Error {
4227
4257
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
4228
4258
  * @property {ContextOptions | boolean} [context] - DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
4229
4259
  * @property {number} [maxAgeHours] - Maximum age of cached content in hours. If content is older, it will be fetched fresh. Special values: 0 = always fetch fresh content, -1 = never fetch fresh (use cached content only). Example: 168 = fetch fresh for pages older than 7 days.
4260
+ * @property {string} [snapshotAsOf] - ISO 8601 datetime. Return the newest stored version at or before this instant instead of live content.
4230
4261
  * @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
4231
4262
  * @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
4232
4263
  * @property {string | string[]} [subpageTarget] - Text used to match/rank subpages in the returned subpage list. You could use "about" to get *about* page for websites. Note that this is a fuzzy matcher.
@@ -4244,6 +4275,7 @@ type ContentsOptions = {
4244
4275
  context?: ContextOptions | true;
4245
4276
  livecrawlTimeout?: number;
4246
4277
  maxAgeHours?: number;
4278
+ snapshotAsOf?: string;
4247
4279
  filterEmptyResults?: boolean;
4248
4280
  subpages?: number;
4249
4281
  subpageTarget?: string | string[];
@@ -4378,6 +4410,14 @@ type NonDeepSearchOptions = BaseRegularSearchOptions & {
4378
4410
  * Uses a discriminated union to ensure additionalQueries is only allowed when type is a deep search variant.
4379
4411
  */
4380
4412
  type RegularSearchOptions = DeepSearchOptions | NonDeepSearchOptions;
4413
+ /**
4414
+ * Options for opting into Exa-Beta features.
4415
+ * @typedef {Object} BetaOptions
4416
+ * @property {string[]} [betas] - Exa-Beta tokens to send with the request (e.g. `[DYNAMIC_HIGHLIGHTS_BETA]` for Dynamic Highlights).
4417
+ */
4418
+ type BetaOptions = {
4419
+ betas?: string[];
4420
+ };
4381
4421
  /**
4382
4422
  * DEPRECATED: Used only by deprecated `findSimilar()` APIs. Use `search()` and `RegularSearchOptions` for new search flows. Will be removed in a future version.
4383
4423
  * @deprecated Use `search()` and `RegularSearchOptions` for new search flows. There is no direct replacement for URL-based similarity.
@@ -4430,13 +4470,15 @@ type TextContentsOptions = {
4430
4470
  * Deep search variants also support these options for returned highlights.
4431
4471
  * @typedef {Object} HighlightsContentsOptions
4432
4472
  * @property {string} [query] - The query string to use for highlights search.
4433
- * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
4473
+ * @property {number} [maxCharacters] - The maximum number of characters to return for highlights. Not compatible with `dynamic`.
4474
+ * @property {boolean} [dynamic] - Enable Dynamic Highlights (research preview): allocates one shared context budget across all results instead of a per-document budget; the model sizes the output itself. Not compatible with `maxCharacters`. Beta: requires passing `betas: [DYNAMIC_HIGHLIGHTS_BETA]` to the request.
4434
4475
  * @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
4435
4476
  * @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
4436
4477
  */
4437
4478
  type HighlightsContentsOptions = {
4438
4479
  query?: string;
4439
4480
  maxCharacters?: number;
4481
+ dynamic?: boolean;
4440
4482
  /**
4441
4483
  * DEPRECATED: Use `maxCharacters` instead. Will be removed in a future version.
4442
4484
  * @deprecated Use `maxCharacters` instead. This legacy sizing field will be removed in a future version.
@@ -4651,6 +4693,7 @@ type Entity = CompanyEntity | PersonEntity;
4651
4693
  * @property {string} id - The temporary ID for the document.
4652
4694
  * @property {string} [image] - A representative image for the content, if any.
4653
4695
  * @property {string} [favicon] - A favicon for the site, if any.
4696
+ * @property {string} [snapshotAt] - Crawl instant of the stored version served for a snapshotAsOf request.
4654
4697
  * @property {Entity[]} [entities] - Structured entity data for company or person search results.
4655
4698
  */
4656
4699
  type SearchResult<T extends ContentsOptions> = {
@@ -4662,6 +4705,7 @@ type SearchResult<T extends ContentsOptions> = {
4662
4705
  id: string;
4663
4706
  image?: string;
4664
4707
  favicon?: string;
4708
+ snapshotAt?: string;
4665
4709
  entities?: Entity[];
4666
4710
  } & ContentsResultComponent<T>;
4667
4711
  type DeepSearchOutputGroundingCitation = {
@@ -4861,7 +4905,7 @@ declare class Exa {
4861
4905
  * @param {RegularSearchOptions & { contents: false }} options - Search options with contents explicitly disabled
4862
4906
  * @returns {Promise<SearchResponse<{}>>} A list of relevant search results without contents.
4863
4907
  */
4864
- search(query: string, options: RegularSearchOptions & {
4908
+ search(query: string, options: RegularSearchOptions & BetaOptions & {
4865
4909
  contents: false | null | undefined;
4866
4910
  }): Promise<SearchResponse<{}>>;
4867
4911
  /**
@@ -4871,7 +4915,7 @@ declare class Exa {
4871
4915
  * @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
4872
4916
  * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
4873
4917
  */
4874
- search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & {
4918
+ search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & BetaOptions & {
4875
4919
  contents: T;
4876
4920
  }): Promise<SearchResponse<T>>;
4877
4921
  /**
@@ -4882,7 +4926,7 @@ declare class Exa {
4882
4926
  * @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
4883
4927
  * @returns {Promise<SearchResponse<{ text: true }>>} A list of relevant search results with text contents.
4884
4928
  */
4885
- search(query: string, options: Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">): Promise<SearchResponse<{
4929
+ search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions): Promise<SearchResponse<{
4886
4930
  text: true;
4887
4931
  }>>;
4888
4932
  /**
@@ -4986,7 +5030,7 @@ declare class Exa {
4986
5030
  * @param {ContentsOptions} [options] - Additional options for retrieving document contents.
4987
5031
  * @returns {Promise<SearchResponse<T>>} A list of document contents for the requested URLs.
4988
5032
  */
4989
- getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T): Promise<SearchResponse<T>>;
5033
+ getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T & BetaOptions): Promise<SearchResponse<T>>;
4990
5034
  /**
4991
5035
  * Generate an answer with Zod schema for strongly typed output
4992
5036
  */
@@ -5056,4 +5100,4 @@ declare class Exa {
5056
5100
  private parseSSEStream;
5057
5101
  }
5058
5102
 
5059
- export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createWebSearchTool, Exa as default };
5103
+ export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type BetaOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, DYNAMIC_HIGHLIGHTS_BETA, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetContentsTool, type GetContentsToolConfig, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createGetContentsTool, createWebSearchTool, Exa as default };
package/dist/index.d.ts CHANGED
@@ -3989,16 +3989,38 @@ type WebSearchToolConfig = RegularSearchOptions & {
3989
3989
  /** Tool description shown to the model. */
3990
3990
  description?: string;
3991
3991
  };
3992
+ type GetContentsToolConfig = ContentsOptions & {
3993
+ /**
3994
+ * Tool name shown to the model. Defaults to `"get_contents"`. Set a custom
3995
+ * name to avoid collisions, or to register multiple differently-configured
3996
+ * contents tools.
3997
+ */
3998
+ name?: string;
3999
+ /** Tool description shown to the model. */
4000
+ description?: string;
4001
+ };
3992
4002
  type ToolNamespace = {
3993
4003
  webSearch(config?: WebSearchToolConfig): WebSearchTool;
4004
+ getContents(config?: GetContentsToolConfig): GetContentsTool;
3994
4005
  };
3995
4006
  type SearchArgs = {
3996
4007
  query: string;
3997
4008
  };
4009
+ type GetContentsArgs = {
4010
+ urls: string[];
4011
+ };
3998
4012
  type WebSearchTool = ExaToolSpec<SearchArgs, SearchResponse<ContentsOptions>>;
4013
+ type GetContentsTool = ExaToolSpec<GetContentsArgs, SearchResponse<ContentsOptions>>;
3999
4014
  declare const DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
4015
+ declare const DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION = "Read the full contents of web pages you already have URLs for, such as pages returned by a search or mentioned by the user.";
4000
4016
  /** Create a `web_search` tool. Defaults to `type: "auto"` and highlights. */
4001
4017
  declare function createWebSearchTool(exa: Exa, registry: ToolRegistry, config?: WebSearchToolConfig): WebSearchTool;
4018
+ /**
4019
+ * Create a `get_contents` tool that reads pages the model already has URLs for.
4020
+ * Inherits `exa.getContents` defaults, which return page text when no content
4021
+ * option is configured.
4022
+ */
4023
+ declare function createGetContentsTool(exa: Exa, registry: ToolRegistry, config?: GetContentsToolConfig): GetContentsTool;
4002
4024
  declare class ToolRegistry {
4003
4025
  private readonly registry;
4004
4026
  register(tool: ExaToolSpec): void;
@@ -4030,6 +4052,8 @@ declare class AnthropicTools {
4030
4052
  constructor(exa: Exa, registry: ToolRegistry);
4031
4053
  /** Anthropic `web_search` tool. Defaults to `auto` + highlights. */
4032
4054
  webSearch(config?: WebSearchToolConfig): AnthropicRunnable;
4055
+ /** Anthropic `get_contents` tool for reading pages by URL. */
4056
+ getContents(config?: GetContentsToolConfig): AnthropicRunnable;
4033
4057
  /**
4034
4058
  * Run the `tool_use` blocks in an assistant message and return the matching
4035
4059
  * `tool_result` blocks. Every `tool_use` block is answered so the follow-up
@@ -4099,6 +4123,8 @@ declare class OpenAIResponsesTools {
4099
4123
  }) => Promise<ResponsesFunctionCallOutput[]>);
4100
4124
  /** Responses API `web_search` tool. Defaults to `auto` + highlights. */
4101
4125
  webSearch(config?: WebSearchToolConfig): OpenAIResponsesRunnable;
4126
+ /** Responses API `get_contents` tool for reading pages by URL. */
4127
+ getContents(config?: GetContentsToolConfig): OpenAIResponsesRunnable;
4102
4128
  /**
4103
4129
  * Run the function calls in a Responses API response (or output item array)
4104
4130
  * and return `function_call_output` items. Every function call is answered
@@ -4118,6 +4144,8 @@ declare class OpenAITools {
4118
4144
  constructor(exa: Exa, registry: ToolRegistry);
4119
4145
  /** Chat Completions `web_search` tool. Defaults to `auto` + highlights. */
4120
4146
  webSearch(config?: WebSearchToolConfig): OpenAIRunnable;
4147
+ /** Chat Completions `get_contents` tool for reading pages by URL. */
4148
+ getContents(config?: GetContentsToolConfig): OpenAIRunnable;
4121
4149
  /**
4122
4150
  * Run the tool calls in a Chat Completions assistant message and return the
4123
4151
  * matching `role: "tool"` messages. Every tool call is answered so the
@@ -4219,6 +4247,8 @@ declare class ExaError extends Error {
4219
4247
  constructor(message: string, statusCode: number, timestamp?: string, path?: string, envelope?: ExaErrorEnvelope);
4220
4248
  }
4221
4249
 
4250
+ /** Exa-Beta token required for Dynamic Highlights (research preview). */
4251
+ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
4222
4252
  /**
4223
4253
  * Options for retrieving page contents
4224
4254
  * @typedef {Object} ContentsOptions
@@ -4227,6 +4257,7 @@ declare class ExaError extends Error {
4227
4257
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
4228
4258
  * @property {ContextOptions | boolean} [context] - DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
4229
4259
  * @property {number} [maxAgeHours] - Maximum age of cached content in hours. If content is older, it will be fetched fresh. Special values: 0 = always fetch fresh content, -1 = never fetch fresh (use cached content only). Example: 168 = fetch fresh for pages older than 7 days.
4260
+ * @property {string} [snapshotAsOf] - ISO 8601 datetime. Return the newest stored version at or before this instant instead of live content.
4230
4261
  * @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
4231
4262
  * @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
4232
4263
  * @property {string | string[]} [subpageTarget] - Text used to match/rank subpages in the returned subpage list. You could use "about" to get *about* page for websites. Note that this is a fuzzy matcher.
@@ -4244,6 +4275,7 @@ type ContentsOptions = {
4244
4275
  context?: ContextOptions | true;
4245
4276
  livecrawlTimeout?: number;
4246
4277
  maxAgeHours?: number;
4278
+ snapshotAsOf?: string;
4247
4279
  filterEmptyResults?: boolean;
4248
4280
  subpages?: number;
4249
4281
  subpageTarget?: string | string[];
@@ -4378,6 +4410,14 @@ type NonDeepSearchOptions = BaseRegularSearchOptions & {
4378
4410
  * Uses a discriminated union to ensure additionalQueries is only allowed when type is a deep search variant.
4379
4411
  */
4380
4412
  type RegularSearchOptions = DeepSearchOptions | NonDeepSearchOptions;
4413
+ /**
4414
+ * Options for opting into Exa-Beta features.
4415
+ * @typedef {Object} BetaOptions
4416
+ * @property {string[]} [betas] - Exa-Beta tokens to send with the request (e.g. `[DYNAMIC_HIGHLIGHTS_BETA]` for Dynamic Highlights).
4417
+ */
4418
+ type BetaOptions = {
4419
+ betas?: string[];
4420
+ };
4381
4421
  /**
4382
4422
  * DEPRECATED: Used only by deprecated `findSimilar()` APIs. Use `search()` and `RegularSearchOptions` for new search flows. Will be removed in a future version.
4383
4423
  * @deprecated Use `search()` and `RegularSearchOptions` for new search flows. There is no direct replacement for URL-based similarity.
@@ -4430,13 +4470,15 @@ type TextContentsOptions = {
4430
4470
  * Deep search variants also support these options for returned highlights.
4431
4471
  * @typedef {Object} HighlightsContentsOptions
4432
4472
  * @property {string} [query] - The query string to use for highlights search.
4433
- * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
4473
+ * @property {number} [maxCharacters] - The maximum number of characters to return for highlights. Not compatible with `dynamic`.
4474
+ * @property {boolean} [dynamic] - Enable Dynamic Highlights (research preview): allocates one shared context budget across all results instead of a per-document budget; the model sizes the output itself. Not compatible with `maxCharacters`. Beta: requires passing `betas: [DYNAMIC_HIGHLIGHTS_BETA]` to the request.
4434
4475
  * @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
4435
4476
  * @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
4436
4477
  */
4437
4478
  type HighlightsContentsOptions = {
4438
4479
  query?: string;
4439
4480
  maxCharacters?: number;
4481
+ dynamic?: boolean;
4440
4482
  /**
4441
4483
  * DEPRECATED: Use `maxCharacters` instead. Will be removed in a future version.
4442
4484
  * @deprecated Use `maxCharacters` instead. This legacy sizing field will be removed in a future version.
@@ -4651,6 +4693,7 @@ type Entity = CompanyEntity | PersonEntity;
4651
4693
  * @property {string} id - The temporary ID for the document.
4652
4694
  * @property {string} [image] - A representative image for the content, if any.
4653
4695
  * @property {string} [favicon] - A favicon for the site, if any.
4696
+ * @property {string} [snapshotAt] - Crawl instant of the stored version served for a snapshotAsOf request.
4654
4697
  * @property {Entity[]} [entities] - Structured entity data for company or person search results.
4655
4698
  */
4656
4699
  type SearchResult<T extends ContentsOptions> = {
@@ -4662,6 +4705,7 @@ type SearchResult<T extends ContentsOptions> = {
4662
4705
  id: string;
4663
4706
  image?: string;
4664
4707
  favicon?: string;
4708
+ snapshotAt?: string;
4665
4709
  entities?: Entity[];
4666
4710
  } & ContentsResultComponent<T>;
4667
4711
  type DeepSearchOutputGroundingCitation = {
@@ -4861,7 +4905,7 @@ declare class Exa {
4861
4905
  * @param {RegularSearchOptions & { contents: false }} options - Search options with contents explicitly disabled
4862
4906
  * @returns {Promise<SearchResponse<{}>>} A list of relevant search results without contents.
4863
4907
  */
4864
- search(query: string, options: RegularSearchOptions & {
4908
+ search(query: string, options: RegularSearchOptions & BetaOptions & {
4865
4909
  contents: false | null | undefined;
4866
4910
  }): Promise<SearchResponse<{}>>;
4867
4911
  /**
@@ -4871,7 +4915,7 @@ declare class Exa {
4871
4915
  * @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
4872
4916
  * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
4873
4917
  */
4874
- search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & {
4918
+ search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & BetaOptions & {
4875
4919
  contents: T;
4876
4920
  }): Promise<SearchResponse<T>>;
4877
4921
  /**
@@ -4882,7 +4926,7 @@ declare class Exa {
4882
4926
  * @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
4883
4927
  * @returns {Promise<SearchResponse<{ text: true }>>} A list of relevant search results with text contents.
4884
4928
  */
4885
- search(query: string, options: Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">): Promise<SearchResponse<{
4929
+ search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions): Promise<SearchResponse<{
4886
4930
  text: true;
4887
4931
  }>>;
4888
4932
  /**
@@ -4986,7 +5030,7 @@ declare class Exa {
4986
5030
  * @param {ContentsOptions} [options] - Additional options for retrieving document contents.
4987
5031
  * @returns {Promise<SearchResponse<T>>} A list of document contents for the requested URLs.
4988
5032
  */
4989
- getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T): Promise<SearchResponse<T>>;
5033
+ getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T & BetaOptions): Promise<SearchResponse<T>>;
4990
5034
  /**
4991
5035
  * Generate an answer with Zod schema for strongly typed output
4992
5036
  */
@@ -5056,4 +5100,4 @@ declare class Exa {
5056
5100
  private parseSSEStream;
5057
5101
  }
5058
5102
 
5059
- export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createWebSearchTool, Exa as default };
5103
+ export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type BetaOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, DYNAMIC_HIGHLIGHTS_BETA, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetContentsTool, type GetContentsToolConfig, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createGetContentsTool, createWebSearchTool, Exa as default };
package/dist/index.js CHANGED
@@ -48,7 +48,9 @@ __export(index_exports, {
48
48
  BetaClient: () => BetaClient,
49
49
  CreateEnrichmentParametersFormat: () => CreateEnrichmentParametersFormat,
50
50
  CreateImportParametersFormat: () => CreateImportParametersFormat,
51
+ DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION: () => DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION,
51
52
  DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION: () => DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION,
53
+ DYNAMIC_HIGHLIGHTS_BETA: () => DYNAMIC_HIGHLIGHTS_BETA,
52
54
  EventType: () => EventType,
53
55
  EventsClient: () => EventsClient,
54
56
  Exa: () => Exa2,
@@ -88,6 +90,7 @@ __export(index_exports, {
88
90
  WebsetStatus: () => WebsetStatus,
89
91
  WebsetWebhooksClient: () => WebsetWebhooksClient,
90
92
  WebsetsClient: () => WebsetsClient,
93
+ createGetContentsTool: () => createGetContentsTool,
91
94
  createWebSearchTool: () => createWebSearchTool,
92
95
  default: () => index_default
93
96
  });
@@ -97,7 +100,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
97
100
  // package.json
98
101
  var package_default = {
99
102
  name: "exa-js",
100
- version: "2.19.0",
103
+ version: "2.22.0",
101
104
  description: "Exa SDK for Node.js and the browser",
102
105
  publishConfig: {
103
106
  access: "public"
@@ -2414,7 +2417,8 @@ var WebsetsClient = class extends WebsetsBaseClient {
2414
2417
  // src/tools/core.ts
2415
2418
  var import_zod2 = require("zod");
2416
2419
  var DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
2417
- function formatSearchResponse(response) {
2420
+ var DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION = "Read the full contents of web pages you already have URLs for, such as pages returned by a search or mentioned by the user.";
2421
+ function formatResults(response, emptyMessage) {
2418
2422
  const formatted = response.results.map((result) => {
2419
2423
  const lines = [
2420
2424
  `Title: ${result.title || "N/A"}`,
@@ -2422,6 +2426,9 @@ function formatSearchResponse(response) {
2422
2426
  `Published: ${result.publishedDate || "N/A"}`,
2423
2427
  `Author: ${result.author || "N/A"}`
2424
2428
  ];
2429
+ if (result.summary) {
2430
+ lines.push(`Summary: ${result.summary}`);
2431
+ }
2425
2432
  if (result.highlights && result.highlights.length > 0) {
2426
2433
  lines.push(`Highlights:
2427
2434
  ${result.highlights.join("\n")}`);
@@ -2430,7 +2437,13 @@ ${result.highlights.join("\n")}`);
2430
2437
  }
2431
2438
  return lines.join("\n");
2432
2439
  }).join("\n\n---\n\n");
2433
- return formatted || "No search results found.";
2440
+ return formatted || emptyMessage;
2441
+ }
2442
+ function formatSearchResponse(response) {
2443
+ return formatResults(response, "No search results found.");
2444
+ }
2445
+ function formatContentsResponse(response) {
2446
+ return formatResults(response, "No contents found.");
2434
2447
  }
2435
2448
  function registerTool(registry, tool) {
2436
2449
  registry.register(tool);
@@ -2493,6 +2506,33 @@ function createWebSearchTool(exa, registry, config = {}) {
2493
2506
  format: formatSearchResponse
2494
2507
  });
2495
2508
  }
2509
+ function createGetContentsTool(exa, registry, config = {}) {
2510
+ const {
2511
+ name = "get_contents",
2512
+ description = DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION,
2513
+ ...contentsOptions
2514
+ } = config;
2515
+ const inputSchema = import_zod2.z.object({
2516
+ urls: import_zod2.z.array(import_zod2.z.string()).describe(
2517
+ "Absolute URLs of the pages to read, including the scheme. Pass several URLs to read them in a single call."
2518
+ )
2519
+ });
2520
+ const jsonSchema = zodToJsonSchema(inputSchema);
2521
+ delete jsonSchema.$schema;
2522
+ return createTool(registry, {
2523
+ name,
2524
+ description,
2525
+ inputSchema,
2526
+ jsonSchema,
2527
+ definition: {
2528
+ name,
2529
+ description,
2530
+ parameters: jsonSchema
2531
+ },
2532
+ execute: ({ urls }) => exa.getContents(urls, contentsOptions),
2533
+ format: formatContentsResponse
2534
+ });
2535
+ }
2496
2536
  var ToolRegistry = class {
2497
2537
  constructor() {
2498
2538
  this.registry = /* @__PURE__ */ new Map();
@@ -2521,6 +2561,10 @@ var AnthropicTools = class {
2521
2561
  webSearch(config) {
2522
2562
  return runnable(createWebSearchTool(this.exa, this.registry, config));
2523
2563
  }
2564
+ /** Anthropic `get_contents` tool for reading pages by URL. */
2565
+ getContents(config) {
2566
+ return runnable(createGetContentsTool(this.exa, this.registry, config));
2567
+ }
2524
2568
  /**
2525
2569
  * Run the `tool_use` blocks in an assistant message and return the matching
2526
2570
  * `tool_result` blocks. Every `tool_use` block is answered so the follow-up
@@ -2649,6 +2693,12 @@ var OpenAIResponsesTools = class {
2649
2693
  createWebSearchTool(this.exa, this.registry, config)
2650
2694
  );
2651
2695
  }
2696
+ /** Responses API `get_contents` tool for reading pages by URL. */
2697
+ getContents(config) {
2698
+ return responsesRunnable(
2699
+ createGetContentsTool(this.exa, this.registry, config)
2700
+ );
2701
+ }
2652
2702
  /**
2653
2703
  * Run the function calls in a Responses API response (or output item array)
2654
2704
  * and return `function_call_output` items. Every function call is answered
@@ -2703,6 +2753,10 @@ var OpenAITools = class {
2703
2753
  webSearch(config) {
2704
2754
  return runnable2(createWebSearchTool(this.exa, this.registry, config));
2705
2755
  }
2756
+ /** Chat Completions `get_contents` tool for reading pages by URL. */
2757
+ getContents(config) {
2758
+ return runnable2(createGetContentsTool(this.exa, this.registry, config));
2759
+ }
2706
2760
  async handleToolCalls(assistantMessage, options) {
2707
2761
  if (isResponsesInput(assistantMessage)) {
2708
2762
  return this.handleResponsesToolCalls(assistantMessage, options);
@@ -2765,6 +2819,7 @@ function isResponsesInput(value) {
2765
2819
  var fetchImpl = typeof global !== "undefined" && global.fetch ? global.fetch : import_cross_fetch.default;
2766
2820
  var HeadersImpl = typeof global !== "undefined" && global.Headers ? global.Headers : import_cross_fetch.Headers;
2767
2821
  var DEFAULT_MAX_CHARACTERS = 1e4;
2822
+ var DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
2768
2823
  var NON_JSON_BODY_SNIPPET_LENGTH = 500;
2769
2824
  async function readResponseBody(response) {
2770
2825
  const text = await response.text();
@@ -2810,7 +2865,8 @@ var Exa2 = class {
2810
2865
  this.agent = new AgentClient(this);
2811
2866
  this.beta = new BetaClient(this.agent);
2812
2867
  this.tools = {
2813
- webSearch: (options) => createWebSearchTool(this, this.toolRegistry, options)
2868
+ webSearch: (options) => createWebSearchTool(this, this.toolRegistry, options),
2869
+ getContents: (options) => createGetContentsTool(this, this.toolRegistry, options)
2814
2870
  };
2815
2871
  this.openai = new OpenAITools(this, this.toolRegistry);
2816
2872
  this.anthropic = new AnthropicTools(this, this.toolRegistry);
@@ -2829,6 +2885,7 @@ var Exa2 = class {
2829
2885
  livecrawl,
2830
2886
  livecrawlTimeout,
2831
2887
  maxAgeHours,
2888
+ snapshotAsOf,
2832
2889
  // DEPRECATED FIELD: preserve legacy `context` only for backward compatibility.
2833
2890
  context,
2834
2891
  ...rest
@@ -2857,6 +2914,8 @@ var Exa2 = class {
2857
2914
  if (livecrawlTimeout !== void 0)
2858
2915
  contentsOptions.livecrawlTimeout = livecrawlTimeout;
2859
2916
  if (maxAgeHours !== void 0) contentsOptions.maxAgeHours = maxAgeHours;
2917
+ if (snapshotAsOf !== void 0)
2918
+ contentsOptions.snapshotAsOf = snapshotAsOf;
2860
2919
  if (context !== void 0) contentsOptions.context = context;
2861
2920
  return {
2862
2921
  contentsOptions,
@@ -2866,6 +2925,7 @@ var Exa2 = class {
2866
2925
  buildSearchRequestBody(query, options) {
2867
2926
  const requestOptions = { ...options ?? {} };
2868
2927
  delete requestOptions.stream;
2928
+ delete requestOptions.betas;
2869
2929
  if (options === void 0 || !("contents" in options)) {
2870
2930
  return {
2871
2931
  query,
@@ -3019,11 +3079,9 @@ var Exa2 = class {
3019
3079
  400 /* BadRequest */
3020
3080
  );
3021
3081
  }
3022
- return await this.request(
3023
- "/search",
3024
- "POST",
3025
- this.buildSearchRequestBody(query, options)
3026
- );
3082
+ const body = this.buildSearchRequestBody(query, options);
3083
+ const betaHeaders = headersForBetas(options?.betas);
3084
+ return betaHeaders ? await this.request("/search", "POST", body, void 0, betaHeaders) : await this.request("/search", "POST", body);
3027
3085
  }
3028
3086
  /**
3029
3087
  * Stream a search response as an async generator of OpenAI-style chat completion chunks.
@@ -3130,11 +3188,13 @@ var Exa2 = class {
3130
3188
  } else {
3131
3189
  requestUrls = urls.map((result) => result.url);
3132
3190
  }
3191
+ const { betas, ...contentsOptions } = options ?? {};
3133
3192
  const payload = {
3134
3193
  urls: requestUrls,
3135
- ...options
3194
+ ...contentsOptions
3136
3195
  };
3137
- return await this.request("/contents", "POST", payload);
3196
+ const betaHeaders = headersForBetas(betas);
3197
+ return betaHeaders ? await this.request("/contents", "POST", payload, void 0, betaHeaders) : await this.request("/contents", "POST", payload);
3138
3198
  }
3139
3199
  async answer(query, options) {
3140
3200
  if (options?.stream) {
@@ -3343,7 +3403,9 @@ var index_default = Exa2;
3343
3403
  BetaClient,
3344
3404
  CreateEnrichmentParametersFormat,
3345
3405
  CreateImportParametersFormat,
3406
+ DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION,
3346
3407
  DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION,
3408
+ DYNAMIC_HIGHLIGHTS_BETA,
3347
3409
  EventType,
3348
3410
  EventsClient,
3349
3411
  Exa,
@@ -3383,6 +3445,7 @@ var index_default = Exa2;
3383
3445
  WebsetStatus,
3384
3446
  WebsetWebhooksClient,
3385
3447
  WebsetsClient,
3448
+ createGetContentsTool,
3386
3449
  createWebSearchTool
3387
3450
  });
3388
3451
  //# sourceMappingURL=index.js.map