exa-js 2.22.0 → 2.22.1

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
@@ -280,17 +280,15 @@ const changes = await exa.beta.agent.monitors.changes.list(monitor.id, {
280
280
  since: "2026-01-01T00:00:00Z",
281
281
  });
282
282
 
283
- // One-shot stateless snapshot of a past news window — no monitor created.
284
- const snapshot = await exa.beta.agent.monitors.snapshots.createAndWait({
283
+ // One-shot backtest of a past news window — no monitor persists.
284
+ const backtest = await exa.beta.agent.monitors.backtests.createAndWait({
285
285
  betas,
286
286
  entities: [{ name: "Acme Corp", domain: "acme.com" }],
287
- fields: [
288
- { name: "funding", description: "New funding rounds" }, // dynamic by default
289
- ],
290
- startDate: "2026-01-01",
291
- endDate: "2026-01-08",
287
+ fields: [{ name: "funding", description: "New funding rounds" }],
288
+ startTime: "2026-01-01T00:00:00Z",
289
+ endTime: "2026-01-08T00:00:00Z",
292
290
  });
293
- console.log(snapshot.data);
291
+ console.log(backtest.data);
294
292
 
295
293
  // Add entities, inspect refresh progress, clean up.
296
294
  await exa.beta.agent.monitors.entities.add(monitor.id, {
package/dist/index.d.mts CHANGED
@@ -388,50 +388,49 @@ interface DeletedAgentMonitor {
388
388
  deleted: true;
389
389
  }
390
390
  /**
391
- * Params for a one-shot, stateless snapshot of entities × fields over an
392
- * explicit past news window — no monitor is created. The window bounds
393
- * dynamic fields only; static fields return present values answered over the
394
- * live web, and the result carries a warning when static fields are included.
391
+ * Params for a one-shot backtest of entities × fields over an explicit past
392
+ * news window. The backtest runs one monitor refresh over the requested
393
+ * window, then tears down its temporary monitor.
395
394
  */
396
- interface CreateAgentMonitorSnapshotParams {
395
+ interface CreateAgentMonitorBacktestParams {
397
396
  entities: CreateAgentMonitorEntityParams[];
398
397
  fields: CreateAgentMonitorFieldParams[];
399
- /** Start of the news window to snapshot, `YYYY-MM-DD` (UTC). */
400
- startDate: string;
401
- /** Hour of startDate the window starts at, 0-23 UTC; omitted means midnight. */
402
- startHour?: number;
403
- /** End of the news window to snapshot, `YYYY-MM-DD` (UTC). */
404
- endDate: string;
405
- /** Hour of endDate the window ends at, 0-23 UTC; omitted means midnight. */
406
- endHour?: number;
407
- }
408
- /** One entity's snapshot result: populated field values plus the news sources read. */
409
- interface AgentMonitorSnapshotEntity {
398
+ /** Start of the news window as an ISO-8601 UTC timestamp. */
399
+ startTime: string;
400
+ /** End of the news window as an ISO-8601 UTC timestamp. */
401
+ endTime: string;
402
+ }
403
+ /** One backtest cell: a value and its grounding citations. */
404
+ interface AgentMonitorBacktestContent {
405
+ value: unknown;
406
+ citations: AgentMonitorCitation[];
407
+ }
408
+ /** One entity's backtest result, with populated cells keyed by field name. */
409
+ interface AgentMonitorBacktestEntity {
410
410
  name: string;
411
- /** Populated values by field name; fields with no update are absent. */
412
- fields: Record<string, string>;
413
- sourceUrls: string[];
411
+ /** Populated cells by field name; fields with no update are absent. */
412
+ contents: Record<string, AgentMonitorBacktestContent>;
414
413
  }
415
- /** The computed body of a finished snapshot, embedded in the job once it completes. */
416
- interface AgentMonitorSnapshotResult {
417
- data: AgentMonitorSnapshotEntity[];
414
+ /** The computed body of a finished backtest, embedded in the job once it completes. */
415
+ interface AgentMonitorBacktestResult {
416
+ data: AgentMonitorBacktestEntity[];
418
417
  failedEntities?: Array<{
419
418
  name: string;
420
419
  reason: string;
421
420
  }>;
422
- /** Caveats about how the snapshot was computed, e.g. static fields ignoring the window. */
421
+ /** Caveats about how the backtest was computed. */
423
422
  warnings?: string[];
424
423
  }
425
- type AgentMonitorSnapshotStatus = "running" | "completed" | "failed";
424
+ type AgentMonitorBacktestStatus = "running" | "completed" | "failed";
426
425
  /**
427
- * A snapshot job: `create` returns it as `running`, and `get` polls it to
426
+ * A backtest job: `create` returns it as `running`, and `get` polls it to
428
427
  * `completed` (result fields present) or `failed`. Jobs expire and read as
429
428
  * 404 after `expiresAt`.
430
429
  */
431
- type AgentMonitorSnapshot = {
430
+ type AgentMonitorBacktest = {
432
431
  id: string;
433
- object: "agent_monitor.snapshot";
434
- /** The snapshotted news window, echoed back as normalized ISO-8601 timestamps. */
432
+ object: "agent_monitor.backtest";
433
+ /** The backtested news window, echoed back as normalized ISO-8601 timestamps. */
435
434
  startTime: string;
436
435
  endTime: string;
437
436
  createdAt: string;
@@ -440,11 +439,11 @@ type AgentMonitorSnapshot = {
440
439
  status: "running";
441
440
  } | ({
442
441
  status: "completed";
443
- } & AgentMonitorSnapshotResult) | {
442
+ } & AgentMonitorBacktestResult) | {
444
443
  status: "failed";
445
444
  error: string;
446
445
  });
447
- interface AgentMonitorSnapshotWaitOptions {
446
+ interface AgentMonitorBacktestWaitOptions {
448
447
  pollInterval?: number;
449
448
  timeoutMs?: number;
450
449
  }
@@ -466,17 +465,17 @@ declare class AgentMonitorsBaseClient {
466
465
  * Client for the Exa Agent Monitors API (`/agent/monitors`).
467
466
  */
468
467
 
469
- type AgentMonitorTerminalSnapshot = AgentMonitorSnapshot & {
468
+ type AgentMonitorTerminalBacktest = AgentMonitorBacktest & {
470
469
  status: "completed" | "failed";
471
470
  };
472
- type AgentMonitorCompletedSnapshot = AgentMonitorSnapshot & {
471
+ type AgentMonitorCompletedBacktest = AgentMonitorBacktest & {
473
472
  status: "completed";
474
473
  };
475
- declare class AgentMonitorSnapshotFailedError extends Error {
476
- snapshot: AgentMonitorSnapshot & {
474
+ declare class AgentMonitorBacktestFailedError extends Error {
475
+ backtest: AgentMonitorBacktest & {
477
476
  status: "failed";
478
477
  };
479
- constructor(snapshot: AgentMonitorSnapshot & {
478
+ constructor(backtest: AgentMonitorBacktest & {
480
479
  status: "failed";
481
480
  });
482
481
  }
@@ -517,27 +516,27 @@ declare class AgentMonitorChangesClient extends AgentMonitorsBaseClient {
517
516
  */
518
517
  getAll(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): Promise<AgentMonitorChange[]>;
519
518
  }
520
- declare class AgentMonitorSnapshotsClient extends AgentMonitorsBaseClient {
519
+ declare class AgentMonitorBacktestsClient extends AgentMonitorsBaseClient {
521
520
  /**
522
- * Start an async, stateless snapshot of entities × fields over an explicit
523
- * past news window — no monitor is created. Returns a `running` job; poll
524
- * with `get` (or use `createAndWait`) for the result.
521
+ * Start an async backtest of entities × fields over an explicit past news
522
+ * window. Returns a `running` job; poll with `get` (or use `createAndWait`)
523
+ * for the result.
525
524
  */
526
- create(params: CreateAgentMonitorSnapshotParams & AgentMonitorsBetaOptions): Promise<AgentMonitorSnapshot>;
525
+ create(params: CreateAgentMonitorBacktestParams & AgentMonitorsBetaOptions): Promise<AgentMonitorBacktest>;
527
526
  /**
528
- * Poll a snapshot job for its status and, once completed, its result.
527
+ * Poll a backtest job for its status and, once completed, its result.
529
528
  * Jobs expire and read as 404 after `expiresAt`.
530
529
  */
531
- get(snapshotId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitorSnapshot>;
530
+ get(backtestId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitorBacktest>;
532
531
  /**
533
- * Poll a snapshot job until it reaches a terminal status.
532
+ * Poll a backtest job until it reaches a terminal status.
534
533
  */
535
- pollUntilFinished(snapshotId: string, options: AgentMonitorSnapshotWaitOptions & AgentMonitorsBetaOptions): Promise<AgentMonitorTerminalSnapshot>;
534
+ pollUntilFinished(backtestId: string, options: AgentMonitorBacktestWaitOptions & AgentMonitorsBetaOptions): Promise<AgentMonitorTerminalBacktest>;
536
535
  /**
537
- * Start a snapshot and wait for its result. Throws
538
- * AgentMonitorSnapshotFailedError if the snapshot fails.
536
+ * Start a backtest and wait for its result. Throws
537
+ * AgentMonitorBacktestFailedError if the backtest fails.
539
538
  */
540
- createAndWait(params: CreateAgentMonitorSnapshotParams & AgentMonitorsBetaOptions, options?: AgentMonitorSnapshotWaitOptions): Promise<AgentMonitorCompletedSnapshot>;
539
+ createAndWait(params: CreateAgentMonitorBacktestParams & AgentMonitorsBetaOptions, options?: AgentMonitorBacktestWaitOptions): Promise<AgentMonitorCompletedBacktest>;
541
540
  }
542
541
  declare class AgentMonitorsClient extends AgentMonitorsBaseClient {
543
542
  /**
@@ -549,9 +548,9 @@ declare class AgentMonitorsClient extends AgentMonitorsBaseClient {
549
548
  */
550
549
  changes: AgentMonitorChangesClient;
551
550
  /**
552
- * Client for stateless snapshot jobs.
551
+ * Client for one-shot backtest jobs.
553
552
  */
554
- snapshots: AgentMonitorSnapshotsClient;
553
+ backtests: AgentMonitorBacktestsClient;
555
554
  constructor(client: Exa);
556
555
  /**
557
556
  * Create an Agent Monitor from its entities, fields, and cadence.
@@ -4253,7 +4252,7 @@ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
4253
4252
  * Options for retrieving page contents
4254
4253
  * @typedef {Object} ContentsOptions
4255
4254
  * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
4256
- * @property {HighlightsContentsOptions | boolean} [highlights] - Options for retrieving highlights.
4255
+ * @property {HighlightsContentsOptions | boolean} [highlights] - Recommended: `true`. Exa dynamically chooses the number of characters based on each document's relevance to your query.
4257
4256
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
4258
4257
  * @property {ContextOptions | boolean} [context] - DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
4259
4258
  * @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.
@@ -4265,6 +4264,14 @@ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
4265
4264
  */
4266
4265
  type ContentsOptions = {
4267
4266
  text?: TextContentsOptions | true;
4267
+ /**
4268
+ * Recommended default: `true`. Exa dynamically chooses the number of
4269
+ * characters based on each document's relevance to your query.
4270
+ * Use this for concise AI context, RAG, and search previews without
4271
+ * choosing a character budget yourself. Read `result.highlights`.
4272
+ * Set `maxCharacters` only when your application has an explicit
4273
+ * character-limit requirement; it overrides the recommended default.
4274
+ */
4268
4275
  highlights?: HighlightsContentsOptions | true;
4269
4276
  summary?: SummaryContentsOptions | true;
4270
4277
  livecrawl?: LivecrawlOptions;
@@ -4466,17 +4473,25 @@ type TextContentsOptions = {
4466
4473
  excludeSections?: SectionTag[];
4467
4474
  };
4468
4475
  /**
4469
- * Options for retrieving highlights from page.
4476
+ * Overrides for highlights. Prefer `highlights: true`: Exa dynamically
4477
+ * chooses the number of characters based on each document's relevance
4478
+ * to your query. A request for concise context does not require setting
4479
+ * a fixed character budget.
4470
4480
  * Deep search variants also support these options for returned highlights.
4471
4481
  * @typedef {Object} HighlightsContentsOptions
4472
4482
  * @property {string} [query] - The query string to use for highlights search.
4473
- * @property {number} [maxCharacters] - The maximum number of characters to return for highlights. Not compatible with `dynamic`.
4483
+ * @property {number} [maxCharacters] - Explicit character-limit override. Prefer `highlights: true` unless your application requires a specific limit. Not compatible with `dynamic`.
4474
4484
  * @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.
4475
4485
  * @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
4476
4486
  * @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
4477
4487
  */
4478
4488
  type HighlightsContentsOptions = {
4479
4489
  query?: string;
4490
+ /**
4491
+ * Override for an explicit application character limit. Prefer
4492
+ * `highlights: true` to let Exa choose the length based on relevance.
4493
+ * A general need for concise context does not require a fixed limit.
4494
+ */
4480
4495
  maxCharacters?: number;
4481
4496
  dynamic?: boolean;
4482
4497
  /**
@@ -4888,7 +4903,15 @@ declare class Exa {
4888
4903
  rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>, headers?: Record<string, string>): Promise<Response>;
4889
4904
  /**
4890
4905
  * Performs a search with an Exa prompt-engineered query.
4891
- * By default, returns text contents. Use contents: false to opt-out.
4906
+ * For AI answers, RAG, and search previews, prefer query-relevant passages:
4907
+ * `exa.search(query, { contents: { highlights: true } })`.
4908
+ * `highlights: true` is the recommended default: Exa dynamically chooses
4909
+ * the number of characters based on each document's relevance to your query.
4910
+ * You do not need to choose `maxCharacters` to keep context concise;
4911
+ * use it only for an explicit application character-limit requirement.
4912
+ * Read each result's `highlights` array. Request `text` only when you need
4913
+ * the full page; use `contents: false` when you only need titles and URLs.
4914
+ * Omitting contents still returns text by default.
4892
4915
  *
4893
4916
  * @param {string} query - The query string.
4894
4917
  * @returns {Promise<SearchResponse<{ text: { maxCharacters: 10_000 } }>>} A list of relevant search results with text contents.
@@ -4910,6 +4933,23 @@ declare class Exa {
4910
4933
  }): Promise<SearchResponse<{}>>;
4911
4934
  /**
4912
4935
  * Performs a search with specific contents.
4936
+ * Prefer `{ contents: { highlights: true } }` for query-relevant passages
4937
+ * for AI answers, RAG, and search previews. Read `result.highlights`.
4938
+ * `highlights: true` is the recommended default: Exa dynamically chooses
4939
+ * the number of characters based on each document's relevance to your query.
4940
+ * No manual character budget is needed. Set `maxCharacters` only when
4941
+ * your application requires a specific numeric character limit; otherwise
4942
+ * keep `highlights: true`.
4943
+ * Use the boolean `true`; do not set the deprecated `numSentences` or
4944
+ * `highlightsPerUrl` options. Request `text` when you need the full page.
4945
+ *
4946
+ * @example
4947
+ * const response = await exa.search("recent advances in battery recycling", {
4948
+ * contents: { highlights: true },
4949
+ * });
4950
+ * for (const result of response.results) {
4951
+ * console.log(result.url, result.highlights);
4952
+ * }
4913
4953
  *
4914
4954
  * @param {string} query - The query string.
4915
4955
  * @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
@@ -4921,6 +4961,8 @@ declare class Exa {
4921
4961
  /**
4922
4962
  * Performs a search with an Exa prompt-engineered query.
4923
4963
  * When no contents option is specified, returns text contents by default.
4964
+ * For query-relevant passages, explicitly pass
4965
+ * `{ contents: { highlights: true } }` and read `result.highlights`.
4924
4966
  *
4925
4967
  * @param {string} query - The query string.
4926
4968
  * @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
@@ -5100,4 +5142,4 @@ declare class Exa {
5100
5142
  private parseSSEStream;
5101
5143
  }
5102
5144
 
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 };
5145
+ 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 AgentMonitorBacktest, type AgentMonitorBacktestContent, type AgentMonitorBacktestEntity, AgentMonitorBacktestFailedError, type AgentMonitorBacktestResult, type AgentMonitorBacktestStatus, type AgentMonitorBacktestWaitOptions, AgentMonitorBacktestsClient, 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 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 CreateAgentMonitorBacktestParams, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, 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
@@ -388,50 +388,49 @@ interface DeletedAgentMonitor {
388
388
  deleted: true;
389
389
  }
390
390
  /**
391
- * Params for a one-shot, stateless snapshot of entities × fields over an
392
- * explicit past news window — no monitor is created. The window bounds
393
- * dynamic fields only; static fields return present values answered over the
394
- * live web, and the result carries a warning when static fields are included.
391
+ * Params for a one-shot backtest of entities × fields over an explicit past
392
+ * news window. The backtest runs one monitor refresh over the requested
393
+ * window, then tears down its temporary monitor.
395
394
  */
396
- interface CreateAgentMonitorSnapshotParams {
395
+ interface CreateAgentMonitorBacktestParams {
397
396
  entities: CreateAgentMonitorEntityParams[];
398
397
  fields: CreateAgentMonitorFieldParams[];
399
- /** Start of the news window to snapshot, `YYYY-MM-DD` (UTC). */
400
- startDate: string;
401
- /** Hour of startDate the window starts at, 0-23 UTC; omitted means midnight. */
402
- startHour?: number;
403
- /** End of the news window to snapshot, `YYYY-MM-DD` (UTC). */
404
- endDate: string;
405
- /** Hour of endDate the window ends at, 0-23 UTC; omitted means midnight. */
406
- endHour?: number;
407
- }
408
- /** One entity's snapshot result: populated field values plus the news sources read. */
409
- interface AgentMonitorSnapshotEntity {
398
+ /** Start of the news window as an ISO-8601 UTC timestamp. */
399
+ startTime: string;
400
+ /** End of the news window as an ISO-8601 UTC timestamp. */
401
+ endTime: string;
402
+ }
403
+ /** One backtest cell: a value and its grounding citations. */
404
+ interface AgentMonitorBacktestContent {
405
+ value: unknown;
406
+ citations: AgentMonitorCitation[];
407
+ }
408
+ /** One entity's backtest result, with populated cells keyed by field name. */
409
+ interface AgentMonitorBacktestEntity {
410
410
  name: string;
411
- /** Populated values by field name; fields with no update are absent. */
412
- fields: Record<string, string>;
413
- sourceUrls: string[];
411
+ /** Populated cells by field name; fields with no update are absent. */
412
+ contents: Record<string, AgentMonitorBacktestContent>;
414
413
  }
415
- /** The computed body of a finished snapshot, embedded in the job once it completes. */
416
- interface AgentMonitorSnapshotResult {
417
- data: AgentMonitorSnapshotEntity[];
414
+ /** The computed body of a finished backtest, embedded in the job once it completes. */
415
+ interface AgentMonitorBacktestResult {
416
+ data: AgentMonitorBacktestEntity[];
418
417
  failedEntities?: Array<{
419
418
  name: string;
420
419
  reason: string;
421
420
  }>;
422
- /** Caveats about how the snapshot was computed, e.g. static fields ignoring the window. */
421
+ /** Caveats about how the backtest was computed. */
423
422
  warnings?: string[];
424
423
  }
425
- type AgentMonitorSnapshotStatus = "running" | "completed" | "failed";
424
+ type AgentMonitorBacktestStatus = "running" | "completed" | "failed";
426
425
  /**
427
- * A snapshot job: `create` returns it as `running`, and `get` polls it to
426
+ * A backtest job: `create` returns it as `running`, and `get` polls it to
428
427
  * `completed` (result fields present) or `failed`. Jobs expire and read as
429
428
  * 404 after `expiresAt`.
430
429
  */
431
- type AgentMonitorSnapshot = {
430
+ type AgentMonitorBacktest = {
432
431
  id: string;
433
- object: "agent_monitor.snapshot";
434
- /** The snapshotted news window, echoed back as normalized ISO-8601 timestamps. */
432
+ object: "agent_monitor.backtest";
433
+ /** The backtested news window, echoed back as normalized ISO-8601 timestamps. */
435
434
  startTime: string;
436
435
  endTime: string;
437
436
  createdAt: string;
@@ -440,11 +439,11 @@ type AgentMonitorSnapshot = {
440
439
  status: "running";
441
440
  } | ({
442
441
  status: "completed";
443
- } & AgentMonitorSnapshotResult) | {
442
+ } & AgentMonitorBacktestResult) | {
444
443
  status: "failed";
445
444
  error: string;
446
445
  });
447
- interface AgentMonitorSnapshotWaitOptions {
446
+ interface AgentMonitorBacktestWaitOptions {
448
447
  pollInterval?: number;
449
448
  timeoutMs?: number;
450
449
  }
@@ -466,17 +465,17 @@ declare class AgentMonitorsBaseClient {
466
465
  * Client for the Exa Agent Monitors API (`/agent/monitors`).
467
466
  */
468
467
 
469
- type AgentMonitorTerminalSnapshot = AgentMonitorSnapshot & {
468
+ type AgentMonitorTerminalBacktest = AgentMonitorBacktest & {
470
469
  status: "completed" | "failed";
471
470
  };
472
- type AgentMonitorCompletedSnapshot = AgentMonitorSnapshot & {
471
+ type AgentMonitorCompletedBacktest = AgentMonitorBacktest & {
473
472
  status: "completed";
474
473
  };
475
- declare class AgentMonitorSnapshotFailedError extends Error {
476
- snapshot: AgentMonitorSnapshot & {
474
+ declare class AgentMonitorBacktestFailedError extends Error {
475
+ backtest: AgentMonitorBacktest & {
477
476
  status: "failed";
478
477
  };
479
- constructor(snapshot: AgentMonitorSnapshot & {
478
+ constructor(backtest: AgentMonitorBacktest & {
480
479
  status: "failed";
481
480
  });
482
481
  }
@@ -517,27 +516,27 @@ declare class AgentMonitorChangesClient extends AgentMonitorsBaseClient {
517
516
  */
518
517
  getAll(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): Promise<AgentMonitorChange[]>;
519
518
  }
520
- declare class AgentMonitorSnapshotsClient extends AgentMonitorsBaseClient {
519
+ declare class AgentMonitorBacktestsClient extends AgentMonitorsBaseClient {
521
520
  /**
522
- * Start an async, stateless snapshot of entities × fields over an explicit
523
- * past news window — no monitor is created. Returns a `running` job; poll
524
- * with `get` (or use `createAndWait`) for the result.
521
+ * Start an async backtest of entities × fields over an explicit past news
522
+ * window. Returns a `running` job; poll with `get` (or use `createAndWait`)
523
+ * for the result.
525
524
  */
526
- create(params: CreateAgentMonitorSnapshotParams & AgentMonitorsBetaOptions): Promise<AgentMonitorSnapshot>;
525
+ create(params: CreateAgentMonitorBacktestParams & AgentMonitorsBetaOptions): Promise<AgentMonitorBacktest>;
527
526
  /**
528
- * Poll a snapshot job for its status and, once completed, its result.
527
+ * Poll a backtest job for its status and, once completed, its result.
529
528
  * Jobs expire and read as 404 after `expiresAt`.
530
529
  */
531
- get(snapshotId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitorSnapshot>;
530
+ get(backtestId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitorBacktest>;
532
531
  /**
533
- * Poll a snapshot job until it reaches a terminal status.
532
+ * Poll a backtest job until it reaches a terminal status.
534
533
  */
535
- pollUntilFinished(snapshotId: string, options: AgentMonitorSnapshotWaitOptions & AgentMonitorsBetaOptions): Promise<AgentMonitorTerminalSnapshot>;
534
+ pollUntilFinished(backtestId: string, options: AgentMonitorBacktestWaitOptions & AgentMonitorsBetaOptions): Promise<AgentMonitorTerminalBacktest>;
536
535
  /**
537
- * Start a snapshot and wait for its result. Throws
538
- * AgentMonitorSnapshotFailedError if the snapshot fails.
536
+ * Start a backtest and wait for its result. Throws
537
+ * AgentMonitorBacktestFailedError if the backtest fails.
539
538
  */
540
- createAndWait(params: CreateAgentMonitorSnapshotParams & AgentMonitorsBetaOptions, options?: AgentMonitorSnapshotWaitOptions): Promise<AgentMonitorCompletedSnapshot>;
539
+ createAndWait(params: CreateAgentMonitorBacktestParams & AgentMonitorsBetaOptions, options?: AgentMonitorBacktestWaitOptions): Promise<AgentMonitorCompletedBacktest>;
541
540
  }
542
541
  declare class AgentMonitorsClient extends AgentMonitorsBaseClient {
543
542
  /**
@@ -549,9 +548,9 @@ declare class AgentMonitorsClient extends AgentMonitorsBaseClient {
549
548
  */
550
549
  changes: AgentMonitorChangesClient;
551
550
  /**
552
- * Client for stateless snapshot jobs.
551
+ * Client for one-shot backtest jobs.
553
552
  */
554
- snapshots: AgentMonitorSnapshotsClient;
553
+ backtests: AgentMonitorBacktestsClient;
555
554
  constructor(client: Exa);
556
555
  /**
557
556
  * Create an Agent Monitor from its entities, fields, and cadence.
@@ -4253,7 +4252,7 @@ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
4253
4252
  * Options for retrieving page contents
4254
4253
  * @typedef {Object} ContentsOptions
4255
4254
  * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
4256
- * @property {HighlightsContentsOptions | boolean} [highlights] - Options for retrieving highlights.
4255
+ * @property {HighlightsContentsOptions | boolean} [highlights] - Recommended: `true`. Exa dynamically chooses the number of characters based on each document's relevance to your query.
4257
4256
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
4258
4257
  * @property {ContextOptions | boolean} [context] - DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
4259
4258
  * @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.
@@ -4265,6 +4264,14 @@ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
4265
4264
  */
4266
4265
  type ContentsOptions = {
4267
4266
  text?: TextContentsOptions | true;
4267
+ /**
4268
+ * Recommended default: `true`. Exa dynamically chooses the number of
4269
+ * characters based on each document's relevance to your query.
4270
+ * Use this for concise AI context, RAG, and search previews without
4271
+ * choosing a character budget yourself. Read `result.highlights`.
4272
+ * Set `maxCharacters` only when your application has an explicit
4273
+ * character-limit requirement; it overrides the recommended default.
4274
+ */
4268
4275
  highlights?: HighlightsContentsOptions | true;
4269
4276
  summary?: SummaryContentsOptions | true;
4270
4277
  livecrawl?: LivecrawlOptions;
@@ -4466,17 +4473,25 @@ type TextContentsOptions = {
4466
4473
  excludeSections?: SectionTag[];
4467
4474
  };
4468
4475
  /**
4469
- * Options for retrieving highlights from page.
4476
+ * Overrides for highlights. Prefer `highlights: true`: Exa dynamically
4477
+ * chooses the number of characters based on each document's relevance
4478
+ * to your query. A request for concise context does not require setting
4479
+ * a fixed character budget.
4470
4480
  * Deep search variants also support these options for returned highlights.
4471
4481
  * @typedef {Object} HighlightsContentsOptions
4472
4482
  * @property {string} [query] - The query string to use for highlights search.
4473
- * @property {number} [maxCharacters] - The maximum number of characters to return for highlights. Not compatible with `dynamic`.
4483
+ * @property {number} [maxCharacters] - Explicit character-limit override. Prefer `highlights: true` unless your application requires a specific limit. Not compatible with `dynamic`.
4474
4484
  * @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.
4475
4485
  * @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
4476
4486
  * @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
4477
4487
  */
4478
4488
  type HighlightsContentsOptions = {
4479
4489
  query?: string;
4490
+ /**
4491
+ * Override for an explicit application character limit. Prefer
4492
+ * `highlights: true` to let Exa choose the length based on relevance.
4493
+ * A general need for concise context does not require a fixed limit.
4494
+ */
4480
4495
  maxCharacters?: number;
4481
4496
  dynamic?: boolean;
4482
4497
  /**
@@ -4888,7 +4903,15 @@ declare class Exa {
4888
4903
  rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>, headers?: Record<string, string>): Promise<Response>;
4889
4904
  /**
4890
4905
  * Performs a search with an Exa prompt-engineered query.
4891
- * By default, returns text contents. Use contents: false to opt-out.
4906
+ * For AI answers, RAG, and search previews, prefer query-relevant passages:
4907
+ * `exa.search(query, { contents: { highlights: true } })`.
4908
+ * `highlights: true` is the recommended default: Exa dynamically chooses
4909
+ * the number of characters based on each document's relevance to your query.
4910
+ * You do not need to choose `maxCharacters` to keep context concise;
4911
+ * use it only for an explicit application character-limit requirement.
4912
+ * Read each result's `highlights` array. Request `text` only when you need
4913
+ * the full page; use `contents: false` when you only need titles and URLs.
4914
+ * Omitting contents still returns text by default.
4892
4915
  *
4893
4916
  * @param {string} query - The query string.
4894
4917
  * @returns {Promise<SearchResponse<{ text: { maxCharacters: 10_000 } }>>} A list of relevant search results with text contents.
@@ -4910,6 +4933,23 @@ declare class Exa {
4910
4933
  }): Promise<SearchResponse<{}>>;
4911
4934
  /**
4912
4935
  * Performs a search with specific contents.
4936
+ * Prefer `{ contents: { highlights: true } }` for query-relevant passages
4937
+ * for AI answers, RAG, and search previews. Read `result.highlights`.
4938
+ * `highlights: true` is the recommended default: Exa dynamically chooses
4939
+ * the number of characters based on each document's relevance to your query.
4940
+ * No manual character budget is needed. Set `maxCharacters` only when
4941
+ * your application requires a specific numeric character limit; otherwise
4942
+ * keep `highlights: true`.
4943
+ * Use the boolean `true`; do not set the deprecated `numSentences` or
4944
+ * `highlightsPerUrl` options. Request `text` when you need the full page.
4945
+ *
4946
+ * @example
4947
+ * const response = await exa.search("recent advances in battery recycling", {
4948
+ * contents: { highlights: true },
4949
+ * });
4950
+ * for (const result of response.results) {
4951
+ * console.log(result.url, result.highlights);
4952
+ * }
4913
4953
  *
4914
4954
  * @param {string} query - The query string.
4915
4955
  * @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
@@ -4921,6 +4961,8 @@ declare class Exa {
4921
4961
  /**
4922
4962
  * Performs a search with an Exa prompt-engineered query.
4923
4963
  * When no contents option is specified, returns text contents by default.
4964
+ * For query-relevant passages, explicitly pass
4965
+ * `{ contents: { highlights: true } }` and read `result.highlights`.
4924
4966
  *
4925
4967
  * @param {string} query - The query string.
4926
4968
  * @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
@@ -5100,4 +5142,4 @@ declare class Exa {
5100
5142
  private parseSSEStream;
5101
5143
  }
5102
5144
 
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 };
5145
+ 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 AgentMonitorBacktest, type AgentMonitorBacktestContent, type AgentMonitorBacktestEntity, AgentMonitorBacktestFailedError, type AgentMonitorBacktestResult, type AgentMonitorBacktestStatus, type AgentMonitorBacktestWaitOptions, AgentMonitorBacktestsClient, 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 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 CreateAgentMonitorBacktestParams, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, 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 };