exa-js 2.12.1 → 2.13.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
@@ -20,15 +20,12 @@ import Exa from "exa-js";
20
20
  const exa = new Exa(process.env.EXA_API_KEY);
21
21
 
22
22
  // Search the web
23
- const result = await exa.search(
24
- "blog post about artificial intelligence",
25
- {
26
- type: "auto",
27
- contents: {
28
- highlights: true
29
- }
30
- }
31
- );
23
+ const result = await exa.search("blog post about artificial intelligence", {
24
+ type: "auto",
25
+ contents: {
26
+ highlights: true,
27
+ },
28
+ });
32
29
 
33
30
  // Get answers with citations
34
31
  const { answer } = await exa.answer("What is the capital of France?");
@@ -44,8 +41,8 @@ const result = await exa.search("interesting articles about space", {
44
41
  includeDomains: ["nasa.gov", "space.com"],
45
42
  startPublishedDate: "2024-01-01",
46
43
  contents: {
47
- highlights: true
48
- }
44
+ highlights: true,
45
+ },
49
46
  });
50
47
  ```
51
48
 
@@ -58,10 +55,10 @@ const resultWithOutput = await exa.search("Who leads OpenAI's safety team?", {
58
55
  properties: {
59
56
  leader: { type: "string" },
60
57
  title: { type: "string" },
61
- sourceCount: { type: "number" }
58
+ sourceCount: { type: "number" },
62
59
  },
63
- required: ["leader", "title"]
64
- }
60
+ required: ["leader", "title"],
61
+ },
65
62
  });
66
63
 
67
64
  console.log(resultWithOutput.output?.content);
@@ -69,7 +66,7 @@ console.log(resultWithOutput.output?.content);
69
66
 
70
67
  ```ts
71
68
  for await (const chunk of exa.streamSearch("Who leads OpenAI's safety team?", {
72
- type: "auto"
69
+ type: "auto",
73
70
  })) {
74
71
  if (chunk.content) {
75
72
  process.stdout.write(chunk.content);
@@ -78,6 +75,7 @@ for await (const chunk of exa.streamSearch("Who leads OpenAI's safety team?", {
78
75
  ```
79
76
 
80
77
  Search `outputSchema` modes:
78
+
81
79
  - `type: "text"`: return plain text in `output.content` (optionally guided by `description`)
82
80
  - `type: "object"`: return structured JSON in `output.content`
83
81
 
@@ -85,10 +83,12 @@ Search `outputSchema` modes:
85
83
  Search streaming is available via `streamSearch(...)`, which yields OpenAI-style chat completion chunks.
86
84
 
87
85
  For `type: "object"`, search currently enforces:
86
+
88
87
  - max nesting depth: `2`
89
88
  - max total properties: `10`
90
89
 
91
90
  Deep search variants that also support `additionalQueries`:
91
+
92
92
  - `deep-lite`
93
93
  - `deep`
94
94
  - `deep-reasoning`
@@ -120,6 +120,41 @@ for await (const chunk of exa.streamAnswer("Explain quantum computing")) {
120
120
  }
121
121
  ```
122
122
 
123
+ ## Agent API (Beta)
124
+
125
+ ```ts
126
+ const run = await exa.beta.agent.runs.create({
127
+ betas: ["agent-2026-05-07"],
128
+ query:
129
+ "Find engineering leaders at AI infrastructure companies that raised a Series A or B in the last 6 months.",
130
+ outputSchema: {
131
+ type: "object",
132
+ properties: {
133
+ people: {
134
+ type: "array",
135
+ maxItems: 10,
136
+ items: {
137
+ type: "object",
138
+ properties: {
139
+ name: { type: "string" },
140
+ contact_email: { type: "string", format: "email" },
141
+ linkedin_url: { type: "string", format: "uri" },
142
+ },
143
+ required: ["name", "linkedin_url"],
144
+ },
145
+ },
146
+ },
147
+ required: ["people"],
148
+ },
149
+ effort: "auto",
150
+ });
151
+
152
+ const completedRun = await exa.beta.agent.runs.pollUntilFinished(run.id, {
153
+ betas: ["agent-2026-05-07"],
154
+ });
155
+ console.log(completedRun.output?.structured);
156
+ ```
157
+
123
158
  ## TypeScript
124
159
 
125
160
  Full TypeScript support with types for all methods.
package/dist/index.d.mts CHANGED
@@ -1,5 +1,222 @@
1
1
  import { ZodSchema } from 'zod';
2
2
 
3
+ /**
4
+ * Types for the Exa Agent API.
5
+ */
6
+
7
+ declare const AGENT_BETA_HEADER = "agent-2026-05-07";
8
+ interface AgentBetaOptions {
9
+ betas: string[];
10
+ }
11
+ type AgentRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
12
+ type AgentStopReason = "schema_satisfied" | "budget_reached" | "error" | "cancelled";
13
+ type AgentConfidence = "low" | "medium" | "high";
14
+ type AgentEffort = "low" | "medium" | "high" | "xhigh" | "auto";
15
+ interface AgentInput {
16
+ data?: Record<string, unknown>[];
17
+ exclusion?: Record<string, unknown>[];
18
+ [key: string]: unknown;
19
+ }
20
+ interface AgentGroundingCitation {
21
+ url: string;
22
+ title?: string | null;
23
+ [key: string]: unknown;
24
+ }
25
+ interface AgentGroundingEntry {
26
+ field: string;
27
+ citations: AgentGroundingCitation[];
28
+ score?: number | null;
29
+ confidence?: AgentConfidence | null;
30
+ [key: string]: unknown;
31
+ }
32
+ interface AgentOutput {
33
+ text?: string | null;
34
+ structured?: unknown;
35
+ grounding?: AgentGroundingEntry[] | null;
36
+ [key: string]: unknown;
37
+ }
38
+ interface AgentUsage {
39
+ agentComputeUnits?: number;
40
+ searches?: number;
41
+ emails?: number;
42
+ phoneNumbers?: number;
43
+ [key: string]: unknown;
44
+ }
45
+ interface AgentCostDollars {
46
+ total?: number;
47
+ agentCompute?: number;
48
+ search?: number;
49
+ emails?: number;
50
+ phoneNumbers?: number;
51
+ [key: string]: unknown;
52
+ }
53
+ interface AgentError {
54
+ type?: string;
55
+ code?: string;
56
+ message?: string;
57
+ path?: string;
58
+ keyword?: string;
59
+ expected?: unknown;
60
+ actual?: unknown;
61
+ [key: string]: unknown;
62
+ }
63
+ interface AgentRun {
64
+ id: string;
65
+ object?: string;
66
+ status: AgentRunStatus;
67
+ stopReason?: AgentStopReason | null;
68
+ createdAt?: string;
69
+ completedAt?: string | null;
70
+ request?: Record<string, unknown>;
71
+ output?: AgentOutput | null;
72
+ usage?: AgentUsage;
73
+ costDollars?: AgentCostDollars;
74
+ error?: AgentError;
75
+ [key: string]: unknown;
76
+ }
77
+ type AgentRunTyped<T> = Omit<AgentRun, "output"> & {
78
+ output?: (Omit<AgentOutput, "structured"> & {
79
+ structured?: T;
80
+ }) | null;
81
+ };
82
+ interface ListAgentRunsParams extends AgentBetaOptions {
83
+ cursor?: string;
84
+ limit?: number;
85
+ }
86
+ interface ListAgentRunsResponse {
87
+ object?: string;
88
+ data: AgentRun[];
89
+ hasMore: boolean;
90
+ nextCursor: string | null;
91
+ }
92
+ interface DeletedAgentRun {
93
+ id: string;
94
+ object?: string;
95
+ deleted: boolean;
96
+ }
97
+ interface AgentEvent {
98
+ id?: string;
99
+ event: string;
100
+ data: Record<string, unknown>;
101
+ createdAt?: string;
102
+ [key: string]: unknown;
103
+ }
104
+ interface ListAgentRunEventsParams extends AgentBetaOptions {
105
+ cursor?: string;
106
+ limit?: number;
107
+ }
108
+ interface ListAgentRunEventsResponse {
109
+ object?: string;
110
+ data: AgentEvent[];
111
+ hasMore: boolean;
112
+ nextCursor: string | null;
113
+ }
114
+ interface CreateAgentRunParams {
115
+ betas: string[];
116
+ query: string;
117
+ systemPrompt?: string;
118
+ input?: AgentInput;
119
+ outputSchema?: Record<string, unknown>;
120
+ effort?: AgentEffort;
121
+ previousRunId?: string;
122
+ metadata?: Record<string, unknown>;
123
+ }
124
+ type CreateAgentRunParamsTyped<T> = Omit<CreateAgentRunParams, "outputSchema"> & {
125
+ outputSchema?: T;
126
+ };
127
+ type AgentCreateOptions<T = Record<string, unknown>> = CreateAgentRunParamsTyped<Record<string, unknown> | ZodSchema<T>> & {
128
+ stream?: boolean;
129
+ };
130
+
131
+ /**
132
+ * Base client for the Exa Agent API.
133
+ */
134
+
135
+ type QueryParams$3 = Record<string, string | number | boolean | string[] | undefined>;
136
+ type RequestBody$2 = Record<string, unknown>;
137
+ declare class AgentBaseClient {
138
+ protected client: Exa;
139
+ constructor(client: Exa);
140
+ protected request<T = unknown>(endpoint: string, betas: string[], method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<T>;
141
+ protected rawRequest(endpoint: string, betas: string[], method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<Response>;
142
+ protected buildPaginationParams(pagination?: ListAgentRunsParams | ListAgentRunEventsParams): QueryParams$3;
143
+ }
144
+
145
+ /**
146
+ * Client for the Exa Agent API.
147
+ */
148
+
149
+ declare class AgentRunEventsClient extends AgentBaseClient {
150
+ /**
151
+ * List stored events for an Agent run.
152
+ */
153
+ list(runId: string, options: ListAgentRunEventsParams): Promise<ListAgentRunEventsResponse>;
154
+ }
155
+ declare class AgentRunsClient extends AgentBaseClient {
156
+ /**
157
+ * Client for Agent run events.
158
+ */
159
+ events: AgentRunEventsClient;
160
+ constructor(client: Exa);
161
+ /**
162
+ * Create an Agent run.
163
+ */
164
+ create<T>(params: AgentCreateOptions<T> & {
165
+ stream: true;
166
+ }): Promise<AsyncGenerator<AgentEvent>>;
167
+ create<T>(params: AgentCreateOptions<T> & {
168
+ stream?: false;
169
+ }): Promise<AgentRunTyped<T>>;
170
+ create(params: CreateAgentRunParams): Promise<AgentRun>;
171
+ /**
172
+ * Get an Agent run by ID.
173
+ */
174
+ get(runId: string, options: AgentBetaOptions): Promise<AgentRun>;
175
+ /**
176
+ * List Agent runs.
177
+ */
178
+ list(options: ListAgentRunsParams): Promise<ListAgentRunsResponse>;
179
+ /**
180
+ * Iterate through all Agent runs, handling pagination automatically.
181
+ */
182
+ listAll(options: ListAgentRunsParams): AsyncGenerator<AgentRun>;
183
+ /**
184
+ * Collect all Agent runs into an array.
185
+ */
186
+ getAll(options: ListAgentRunsParams): Promise<AgentRun[]>;
187
+ /**
188
+ * Cancel a queued or running Agent run.
189
+ */
190
+ cancel(runId: string, options: AgentBetaOptions): Promise<AgentRun>;
191
+ /**
192
+ * Delete a stored Agent run.
193
+ */
194
+ delete(runId: string, options: AgentBetaOptions): Promise<DeletedAgentRun>;
195
+ /**
196
+ * Poll an Agent run until it reaches a terminal status.
197
+ */
198
+ pollUntilFinished(runId: string, options: AgentBetaOptions & {
199
+ pollInterval?: number;
200
+ timeoutMs?: number;
201
+ }): Promise<AgentRun & {
202
+ status: "completed" | "failed" | "cancelled";
203
+ }>;
204
+ }
205
+ declare class AgentBetaClient {
206
+ /**
207
+ * Client for Agent runs.
208
+ */
209
+ runs: AgentRunsClient;
210
+ constructor(client: Exa);
211
+ }
212
+ declare class BetaClient {
213
+ /**
214
+ * Beta Agent namespace.
215
+ */
216
+ agent: AgentBetaClient;
217
+ constructor(client: Exa);
218
+ }
219
+
3
220
  /**
4
221
  * Types for the Search Monitors API
5
222
  */
@@ -3256,6 +3473,7 @@ declare class ExaError extends Error {
3256
3473
  * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
3257
3474
  * @property {HighlightsContentsOptions | boolean} [highlights] - Options for retrieving highlights.
3258
3475
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
3476
+ * @property {ContextOptions | boolean} [context] - DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
3259
3477
  * @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.
3260
3478
  * @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
3261
3479
  * @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
@@ -3267,7 +3485,10 @@ type ContentsOptions = {
3267
3485
  highlights?: HighlightsContentsOptions | true;
3268
3486
  summary?: SummaryContentsOptions | true;
3269
3487
  livecrawl?: LivecrawlOptions;
3270
- /** @deprecated Use `highlights` or `text` instead. Will be removed in a future version. */
3488
+ /**
3489
+ * DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
3490
+ * @deprecated Use `text` or `highlights` instead. This legacy `context` field will be removed in a future version.
3491
+ */
3271
3492
  context?: ContextOptions | true;
3272
3493
  livecrawlTimeout?: number;
3273
3494
  maxAgeHours?: number;
@@ -3368,11 +3589,13 @@ type DeepObjectOutputSchema = {
3368
3589
  type DeepOutputSchema = DeepTextOutputSchema | DeepObjectOutputSchema;
3369
3590
  /**
3370
3591
  * Contents options for deep search.
3371
- * @deprecated The `context` field is deprecated. Use `highlights` or `text` instead.
3372
3592
  */
3373
3593
  type DeepContentsOptions = Omit<ContentsOptions, "context"> & {
3374
- /** @deprecated Use `highlights` or `text` instead. Will be removed in a future version. */
3375
- context?: Omit<ContextOptions, never> | true;
3594
+ /**
3595
+ * DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
3596
+ * @deprecated Use `text` or `highlights` instead. This legacy `context` field will be removed in a future version.
3597
+ */
3598
+ context?: ContextOptions | true;
3376
3599
  };
3377
3600
  /**
3378
3601
  * Search options for deep search types, which additionally support additional queries.
@@ -3402,6 +3625,9 @@ type NonDeepSearchOptions = BaseRegularSearchOptions & {
3402
3625
  */
3403
3626
  type RegularSearchOptions = DeepSearchOptions | NonDeepSearchOptions;
3404
3627
  /**
3628
+ * DEPRECATED: Used only by deprecated `findSimilar()` APIs. Use `search()` and `RegularSearchOptions` for new search flows. Will be removed in a future version.
3629
+ * @deprecated Use `search()` and `RegularSearchOptions` for new search flows. There is no direct replacement for URL-based similarity.
3630
+ *
3405
3631
  * Options for finding similar links.
3406
3632
  * @typedef {Object} FindSimilarOptions
3407
3633
  * @property {boolean} [excludeSourceDomain] - If true, excludes links from the base domain of the input.
@@ -3451,33 +3677,41 @@ type TextContentsOptions = {
3451
3677
  * @typedef {Object} HighlightsContentsOptions
3452
3678
  * @property {string} [query] - The query string to use for highlights search.
3453
3679
  * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
3454
- * @property {number} [numSentences] - Deprecated. Use maxCharacters instead.
3455
- * @property {number} [highlightsPerUrl] - Deprecated. Use maxCharacters instead.
3680
+ * @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
3681
+ * @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
3456
3682
  */
3457
3683
  type HighlightsContentsOptions = {
3458
3684
  query?: string;
3459
3685
  maxCharacters?: number;
3460
- /** @deprecated Use maxCharacters instead */
3686
+ /**
3687
+ * DEPRECATED: Use `maxCharacters` instead. Will be removed in a future version.
3688
+ * @deprecated Use `maxCharacters` instead. This legacy sizing field will be removed in a future version.
3689
+ */
3461
3690
  numSentences?: number;
3462
- /** @deprecated Use maxCharacters instead */
3691
+ /**
3692
+ * DEPRECATED: Use `maxCharacters` instead. Will be removed in a future version.
3693
+ * @deprecated Use `maxCharacters` instead. This legacy sizing field will be removed in a future version.
3694
+ */
3463
3695
  highlightsPerUrl?: number;
3464
3696
  };
3465
3697
  /**
3466
3698
  * Options for retrieving summary from page.
3467
3699
  * @typedef {Object} SummaryContentsOptions
3468
3700
  * @property {string} [query] - The query string to use for summary generation.
3469
- * @property {JSONSchema} [schema] - JSON schema for structured output from summary.
3701
+ * @property {Record<string, unknown> | ZodSchema} [schema] - JSON schema for structured output from summary.
3470
3702
  */
3471
3703
  type SummaryContentsOptions = {
3472
3704
  query?: string;
3473
3705
  schema?: Record<string, unknown> | ZodSchema;
3474
3706
  };
3475
3707
  /**
3476
- * @deprecated Use Record<string, unknown> instead.
3708
+ * DEPRECATED: Use `Record<string, unknown>` instead. Will be removed in a future version.
3709
+ * @deprecated Use `Record<string, unknown>` instead.
3477
3710
  */
3478
3711
  type JSONSchema = Record<string, unknown>;
3479
3712
  /**
3480
- * @deprecated Use `highlights` or `text` instead. The `context` option is deprecated and will be removed in a future version.
3713
+ * DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
3714
+ * @deprecated Use `text` or `highlights` instead. The `context` option will be removed in a future version.
3481
3715
  *
3482
3716
  * Options for retrieving the context from a list of search results. The context is a string
3483
3717
  * representation of all the search results.
@@ -3694,7 +3928,7 @@ type DeepSearchOutput = {
3694
3928
  * Represents a search response object.
3695
3929
  * @typedef {Object} SearchResponse
3696
3930
  * @property {Result[]} results - The list of search results.
3697
- * @property {string} [context] - Deprecated. The context for the search.
3931
+ * @property {string} [context] - DEPRECATED: Use `text` or `highlights` on individual results instead. Will be removed in a future version.
3698
3932
  * @property {DeepSearchOutput} [output] - Search synthesized output object returned when `outputSchema` is provided.
3699
3933
  * @property {string} [autoDate] - The autoprompt date, if applicable.
3700
3934
  * @property {string} requestId - The request ID for the search.
@@ -3704,7 +3938,10 @@ type DeepSearchOutput = {
3704
3938
  */
3705
3939
  type SearchResponse<T extends ContentsOptions> = {
3706
3940
  results: SearchResult<T>[];
3707
- /** @deprecated Use `highlights` or `text` on individual results instead. Will be removed in a future version. */
3941
+ /**
3942
+ * DEPRECATED: Use `text` or `highlights` on individual results instead. Will be removed in a future version.
3943
+ * @deprecated Use `text` or `highlights` on individual results instead. This legacy `context` field will be removed in a future version.
3944
+ */
3708
3945
  context?: string;
3709
3946
  output?: DeepSearchOutput;
3710
3947
  autoDate?: string;
@@ -3814,6 +4051,10 @@ declare class Exa {
3814
4051
  * Search Monitors API client
3815
4052
  */
3816
4053
  monitors: SearchMonitorsClient;
4054
+ /**
4055
+ * Beta API clients
4056
+ */
4057
+ beta: BetaClient;
3817
4058
  /**
3818
4059
  * Helper method to separate out the contents-specific options from the rest.
3819
4060
  */
@@ -3835,7 +4076,7 @@ declare class Exa {
3835
4076
  * @throws {ExaError} When any API request fails with structured error information
3836
4077
  */
3837
4078
  request<T = unknown>(endpoint: string, method: string, body?: any, params?: Record<string, any>, headers?: Record<string, string>): Promise<T>;
3838
- rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>): Promise<Response>;
4079
+ rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>, headers?: Record<string, string>): Promise<Response>;
3839
4080
  /**
3840
4081
  * Performs a search with an Exa prompt-engineered query.
3841
4082
  * By default, returns text contents. Use contents: false to opt-out.
@@ -3889,6 +4130,7 @@ declare class Exa {
3889
4130
  contents?: ContentsOptions | false | null | undefined;
3890
4131
  }): AsyncGenerator<SearchStreamChunk>;
3891
4132
  /**
4133
+ * DEPRECATED: Use `search()` instead. This legacy wrapper will be removed in a future version.
3892
4134
  * @deprecated Use `search()` instead. The search method now returns text contents by default.
3893
4135
  *
3894
4136
  * Migration examples:
@@ -3896,7 +4138,7 @@ declare class Exa {
3896
4138
  * - `searchAndContents(query, { text: true })` → `search(query, { contents: { text: true } })`
3897
4139
  * - `searchAndContents(query, { summary: true })` → `search(query, { contents: { summary: true } })`
3898
4140
  *
3899
- * Performs a search with an Exa prompt-engineered query and returns the contents of the documents.
4141
+ * Compatibility wrapper for the legacy top-level contents options shape.
3900
4142
  *
3901
4143
  * @param {string} query - The query string.
3902
4144
  * @param {RegularSearchOptions & T} [options] - Additional search + contents options
@@ -3904,6 +4146,9 @@ declare class Exa {
3904
4146
  */
3905
4147
  searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T): Promise<SearchResponse<T>>;
3906
4148
  /**
4149
+ * DEPRECATED: Use `search()` for new discovery flows. There is no direct replacement for URL-based similarity.
4150
+ * @deprecated Use `search()` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
4151
+ *
3907
4152
  * Finds similar links to the provided URL.
3908
4153
  * By default, returns text contents. Use contents: false to opt-out.
3909
4154
  *
@@ -3916,6 +4161,9 @@ declare class Exa {
3916
4161
  };
3917
4162
  }>>;
3918
4163
  /**
4164
+ * DEPRECATED: Use `search()` for new discovery flows. There is no direct replacement for URL-based similarity.
4165
+ * @deprecated Use `search()` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
4166
+ *
3919
4167
  * Finds similar links to the provided URL without contents.
3920
4168
  *
3921
4169
  * @param {string} url - The URL for which to find similar links.
@@ -3926,6 +4174,9 @@ declare class Exa {
3926
4174
  contents: false | null | undefined;
3927
4175
  }): Promise<SearchResponse<{}>>;
3928
4176
  /**
4177
+ * DEPRECATED: Use `search()` with `contents` for new discovery flows. There is no direct replacement for URL-based similarity.
4178
+ * @deprecated Use `search()` with `contents` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
4179
+ *
3929
4180
  * Finds similar links to the provided URL with specific contents.
3930
4181
  *
3931
4182
  * @param {string} url - The URL for which to find similar links.
@@ -3936,6 +4187,9 @@ declare class Exa {
3936
4187
  contents: T;
3937
4188
  }): Promise<SearchResponse<T>>;
3938
4189
  /**
4190
+ * DEPRECATED: Use `search()` for new discovery flows. There is no direct replacement for URL-based similarity.
4191
+ * @deprecated Use `search()` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
4192
+ *
3939
4193
  * Finds similar links to the provided URL.
3940
4194
  * When no contents option is specified, returns text contents by default.
3941
4195
  *
@@ -3947,14 +4201,15 @@ declare class Exa {
3947
4201
  text: true;
3948
4202
  }>>;
3949
4203
  /**
3950
- * @deprecated Use `findSimilar()` instead. The findSimilar method now returns text contents by default.
4204
+ * DEPRECATED: Use `search()` for new discovery flows instead. This legacy wrapper will be removed in a future version.
4205
+ * @deprecated Use `search()` for new discovery flows instead. There is no direct replacement for URL-based similarity.
3951
4206
  *
3952
4207
  * Migration examples:
3953
- * - `findSimilarAndContents(url)` → `findSimilar(url)`
3954
- * - `findSimilarAndContents(url, { text: true })` → `findSimilar(url, { contents: { text: true } })`
3955
- * - `findSimilarAndContents(url, { summary: true })` → `findSimilar(url, { contents: { summary: true } })`
4208
+ * - `findSimilarAndContents(url)` → `search(query)`
4209
+ * - `findSimilarAndContents(url, { text: true })` → `search(query, { contents: { text: true } })`
4210
+ * - `findSimilarAndContents(url, { summary: true })` → `search(query, { contents: { summary: true } })`
3956
4211
  *
3957
- * Finds similar links to the provided URL and returns the contents of the documents.
4212
+ * Compatibility wrapper for the legacy top-level contents options shape.
3958
4213
  * @param {string} url - The URL for which to find similar links.
3959
4214
  * @param {FindSimilarOptions & T} [options] - Additional options for finding similar links + contents.
3960
4215
  * @returns {Promise<SearchResponse<T>>} A list of similar search results, including requested contents.
@@ -4036,4 +4291,4 @@ declare class Exa {
4036
4291
  private parseSSEStream;
4037
4292
  }
4038
4293
 
4039
- export { type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, 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, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, 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 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 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, 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 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 TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, 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, Exa as default };
4294
+ export { AGENT_BETA_HEADER, AgentBetaClient, type AgentBetaOptions, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentOutput, type AgentRun, AgentRunEventsClient, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, BetaClient, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, 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, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, 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 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 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, 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 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 TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, 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, Exa as default };