exa-js 2.26.0 → 2.28.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
@@ -67,6 +67,7 @@ console.log(resultWithOutput.output?.content);
67
67
  ```ts
68
68
  for await (const chunk of exa.streamSearch("Who leads OpenAI's safety team?", {
69
69
  type: "auto",
70
+ outputSchema: { type: "text" },
70
71
  })) {
71
72
  if (chunk.content) {
72
73
  process.stdout.write(chunk.content);
@@ -79,14 +80,17 @@ Search `outputSchema` modes:
79
80
  - `type: "text"`: return plain text in `output.content` (optionally guided by `description`)
80
81
  - `type: "object"`: return structured JSON in `output.content`
81
82
 
82
- `systemPrompt` and `outputSchema` are supported on every search type.
83
+ `systemPrompt` and `outputSchema` are supported on every search type except `lite`.
83
84
  Search streaming is available via `streamSearch(...)`, which yields OpenAI-style chat completion chunks.
85
+ A search without `outputSchema` has no text to stream. Its stream yields one chunk with the results as `citations`.
84
86
 
85
87
  For `type: "object"`, search currently enforces:
86
88
 
87
89
  - max nesting depth: `2`
88
90
  - max total properties: `10`
89
91
 
92
+ A schema can be declared outside the call (`as const`, or `satisfies DeepOutputSchema`).
93
+
90
94
  Deep search variants that also support `additionalQueries`:
91
95
 
92
96
  - `deep-lite`
@@ -125,6 +129,10 @@ for await (const chunk of exa.streamAnswer("Explain quantum computing")) {
125
129
  if (chunk.content) {
126
130
  process.stdout.write(chunk.content);
127
131
  }
132
+ // The last chunk carries the cost.
133
+ if (chunk.costDollars) {
134
+ console.log("\nCost:", chunk.costDollars.total);
135
+ }
128
136
  }
129
137
  ```
130
138
 
@@ -187,7 +195,7 @@ const completion = await openai.chat.completions.create({
187
195
  messages,
188
196
  tools: [
189
197
  exa.openai.webSearch(),
190
- exa.openai.getContents({ summary: true, livecrawl: "preferred" }),
198
+ exa.openai.getContents({ summary: true, maxAgeHours: 1 }),
191
199
  ],
192
200
  });
193
201
  ```
@@ -434,7 +442,6 @@ import type { SearchResponse, RegularSearchOptions } from "exa-js";
434
442
 
435
443
  - [Documentation](https://exa.ai/docs)
436
444
  - [API Reference](https://exa.ai/docs/reference/search)
437
- - [Examples](./examples)
438
445
 
439
446
  ## Contributing
440
447
 
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { ZodSchema, z } from 'zod';
1
+ import { z } from 'zod/v3';
2
2
 
3
3
  /**
4
4
  * Transport-level options for a single request.
@@ -86,6 +86,18 @@ declare abstract class RequestScopedClient {
86
86
  protected forNextPage(): this;
87
87
  }
88
88
 
89
+ /**
90
+ * A zod 3 schema whose output is `T`, typed by shape rather than as zod's
91
+ * `ZodType`: under `moduleResolution: node`, zod 3.25 resolves `zod` and
92
+ * `zod/v3` to different declaration files, and comparing a caller's schema
93
+ * across them exhausts the TypeScript checker. `_parse` exists only on zod 3
94
+ * schemas, so zod 4 schemas are still rejected at compile time.
95
+ */
96
+ type ZodSchema<T = any> = {
97
+ readonly _output: T;
98
+ _parse(input: any): any;
99
+ };
100
+
89
101
  /**
90
102
  * Types for the Exa Agent API.
91
103
  */
@@ -102,9 +114,23 @@ interface AgentBetaOptions {
102
114
  */
103
115
  betas?: string[];
104
116
  }
105
- type AgentRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
106
- type AgentStopReason = "schema_satisfied" | "budget_reached" | "time_limit_reached" | "stopped" | "error" | "cancelled";
107
- type AgentConfidence = "low" | "medium" | "high";
117
+ type KnownAgentRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
118
+ /**
119
+ * Agent run status. A value not in `KnownAgentRunStatus` is kept as a string.
120
+ */
121
+ type AgentRunStatus = KnownAgentRunStatus | (string & {});
122
+ type KnownAgentStopReason = "schema_satisfied" | "budget_reached" | "time_limit_reached" | "token_limit_reached" | "iteration_limit_reached" | "stopped" | "error" | "cancelled";
123
+ /**
124
+ * Why an Agent run stopped. A value not in `KnownAgentStopReason` is kept as
125
+ * a string.
126
+ */
127
+ type AgentStopReason = KnownAgentStopReason | (string & {});
128
+ type KnownAgentConfidence = "low" | "medium" | "high";
129
+ /**
130
+ * Confidence of a grounding entry. A value not in `KnownAgentConfidence` is
131
+ * kept as a string.
132
+ */
133
+ type AgentConfidence = KnownAgentConfidence | (string & {});
108
134
  type AgentEffort = "minimal" | "low" | "medium" | "high" | "xhigh" | "auto" | "ultra" | "max";
109
135
  /** Per-run spend ceiling for the metered `auto` and `ultra` efforts. */
110
136
  interface AgentBudget {
@@ -290,7 +316,12 @@ interface AgentMonitorsBetaOptions {
290
316
  /** Beta feature identifiers to enable for this request. */
291
317
  betas: string[];
292
318
  }
293
- type AgentMonitorStatus = "creating" | "pending_first_refresh" | "active";
319
+ type KnownAgentMonitorStatus = "creating" | "pending_first_refresh" | "active";
320
+ /**
321
+ * Agent Monitor status. A value not in `KnownAgentMonitorStatus` is kept as a
322
+ * string.
323
+ */
324
+ type AgentMonitorStatus = KnownAgentMonitorStatus | (string & {});
294
325
  type AgentMonitorFieldMode = "static" | "dynamic";
295
326
  /** The type of a field's cell values. */
296
327
  type AgentMonitorFieldValueType = "string" | "number" | "boolean" | "date" | "url" | "email" | "phone";
@@ -301,8 +332,8 @@ interface AgentMonitorField {
301
332
  description: string;
302
333
  /** @deprecated Not returned by the API. */
303
334
  mode?: AgentMonitorFieldMode;
304
- /** The type of the field's cell values. */
305
- type: AgentMonitorFieldValueType;
335
+ /** The type of the field's cell values. A value not listed is kept as a string. */
336
+ type: AgentMonitorFieldValueType | (string & {});
306
337
  }
307
338
  /** An entity tracked by the monitor. */
308
339
  interface AgentMonitorEntity {
@@ -387,7 +418,8 @@ interface AgentMonitorChangeField {
387
418
  }
388
419
  /** One content change from the monitor's change feed. */
389
420
  interface AgentMonitorChange {
390
- type: "content.upserted";
421
+ /** Kind of change. A value not listed is kept as a string. */
422
+ type: "content.upserted" | (string & {});
391
423
  entity: AgentMonitorChangeEntity;
392
424
  field: AgentMonitorChangeField;
393
425
  content: AgentMonitorContent;
@@ -411,8 +443,10 @@ interface CreateAgentMonitorFieldParams {
411
443
  * The type of the field's values. Defaults to `"string"`. Values are
412
444
  * converted to this type where possible. An unsupported type fails the
413
445
  * request, including the deprecated values `"static"` and `"dynamic"`.
446
+ * Accepts any type a monitor's field returns, so `monitor.fields` can be
447
+ * passed back.
414
448
  */
415
- type?: AgentMonitorFieldValueType | AgentMonitorFieldMode;
449
+ type?: AgentMonitorField["type"] | AgentMonitorFieldMode;
416
450
  /** @deprecated Omit this field. The API rejects requests that set it. */
417
451
  mode?: AgentMonitorFieldMode;
418
452
  }
@@ -845,10 +879,30 @@ declare class BetaClient {
845
879
  * Types for the Search Monitors API
846
880
  */
847
881
 
848
- type SearchMonitorStatus = "active" | "paused" | "disabled";
849
- type SearchMonitorRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
850
- type SearchMonitorRunFailReason = "api_key_invalid" | "insufficient_credits" | "invalid_params" | "rate_limited" | "search_unavailable" | "search_failed" | "internal_error";
851
- type SearchMonitorWebhookEvent = "monitor.created" | "monitor.updated" | "monitor.deleted" | "monitor.run.created" | "monitor.run.completed";
882
+ type KnownSearchMonitorStatus = "active" | "paused" | "disabled";
883
+ /**
884
+ * Search Monitor status. A value not in `KnownSearchMonitorStatus` is kept as
885
+ * a string.
886
+ */
887
+ type SearchMonitorStatus = KnownSearchMonitorStatus | (string & {});
888
+ type KnownSearchMonitorRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
889
+ /**
890
+ * Search Monitor run status. A value not in `KnownSearchMonitorRunStatus` is
891
+ * kept as a string.
892
+ */
893
+ type SearchMonitorRunStatus = KnownSearchMonitorRunStatus | (string & {});
894
+ type KnownSearchMonitorRunFailReason = "api_key_invalid" | "insufficient_credits" | "invalid_params" | "rate_limited" | "source_not_available" | "forbidden" | "search_unavailable" | "search_failed" | "internal_error";
895
+ /**
896
+ * Why a monitor run failed. A value not in `KnownSearchMonitorRunFailReason`
897
+ * is kept as a string.
898
+ */
899
+ type SearchMonitorRunFailReason = KnownSearchMonitorRunFailReason | (string & {});
900
+ type KnownSearchMonitorWebhookEvent = "monitor.created" | "monitor.updated" | "monitor.deleted" | "monitor.run.created" | "monitor.run.completed";
901
+ /**
902
+ * Search Monitor webhook event. A value not in
903
+ * `KnownSearchMonitorWebhookEvent` is kept as a string.
904
+ */
905
+ type SearchMonitorWebhookEvent = KnownSearchMonitorWebhookEvent | (string & {});
852
906
  interface SearchMonitorSearch {
853
907
  query: string;
854
908
  numResults?: number;
@@ -857,7 +911,8 @@ interface SearchMonitorSearch {
857
911
  contents?: ContentsOptions;
858
912
  }
859
913
  interface SearchMonitorTrigger {
860
- type: "interval";
914
+ /** The trigger type. A value not listed is kept as a string. */
915
+ type: "interval" | (string & {});
861
916
  period: string;
862
917
  }
863
918
  interface SearchMonitorWebhook {
@@ -871,15 +926,16 @@ interface GroundingCitation {
871
926
  interface GroundingEntry {
872
927
  field: string;
873
928
  citations: GroundingCitation[];
874
- confidence: "low" | "medium" | "high";
929
+ /** A value not listed is kept as a string. */
930
+ confidence: "low" | "medium" | "high" | (string & {});
875
931
  }
876
932
  interface SearchMonitorRunOutput {
877
933
  results?: Record<string, unknown>[] | null;
878
934
  /**
879
- * Synthesized output. When the monitor is configured with an `outputSchema`,
880
- * the API returns this as a structured object; otherwise it is a string.
935
+ * Synthesized output. Text for a text `outputSchema`, otherwise JSON matching
936
+ * the schema.
881
937
  */
882
- content?: string | Record<string, unknown> | null;
938
+ content?: string | number | boolean | Record<string, unknown> | unknown[] | null;
883
939
  grounding?: GroundingEntry[] | null;
884
940
  }
885
941
  interface SearchMonitor {
@@ -4498,6 +4554,10 @@ type ContentsOptions = {
4498
4554
  */
4499
4555
  highlights?: HighlightsContentsOptions | true;
4500
4556
  summary?: SummaryContentsOptions | true;
4557
+ /**
4558
+ * @deprecated Use `maxAgeHours` instead. Does not guarantee freshly fetched
4559
+ * content. Cannot be combined with `maxAgeHours`.
4560
+ */
4501
4561
  livecrawl?: LivecrawlOptions;
4502
4562
  /**
4503
4563
  * @deprecated Use `text` or `highlights` instead.
@@ -4511,6 +4571,20 @@ type ContentsOptions = {
4511
4571
  subpageTarget?: string | string[];
4512
4572
  extras?: ExtrasOptions;
4513
4573
  };
4574
+ /**
4575
+ * Rejects contents options `T` that set both `maxAgeHours` and the deprecated
4576
+ * `livecrawl`, which the API refuses together. The compiler reports the error
4577
+ * on `livecrawl`, with the message below. Options that set one of them, or
4578
+ * neither, are unaffected.
4579
+ */
4580
+ type ExclusiveFreshnessOptions<T> = T extends {
4581
+ maxAgeHours: number;
4582
+ livecrawl: LivecrawlOptions;
4583
+ } ? {
4584
+ livecrawl: {
4585
+ "Use maxAgeHours instead. livecrawl cannot be combined with maxAgeHours.": never;
4586
+ };
4587
+ } : unknown;
4514
4588
  /**
4515
4589
  * Contents options for search requests: `ContentsOptions`, with subpage
4516
4590
  * crawling deprecated. To crawl subpages, pass the result URLs to
@@ -4711,6 +4785,7 @@ type DeepTextOutputSchema = {
4711
4785
  };
4712
4786
  /**
4713
4787
  * Deep search output schema mode for structured JSON object responses.
4788
+ * Accepts any other JSON Schema keyword, and schemas declared `as const`.
4714
4789
  */
4715
4790
  type DeepObjectOutputSchema = {
4716
4791
  type: "object";
@@ -4721,7 +4796,9 @@ type DeepObjectOutputSchema = {
4721
4796
  /**
4722
4797
  * Required property names.
4723
4798
  */
4724
- required?: string[];
4799
+ required?: readonly string[];
4800
+ additionalProperties?: boolean;
4801
+ [keyword: string]: unknown;
4725
4802
  };
4726
4803
  /**
4727
4804
  * Search output schema.
@@ -4822,6 +4899,8 @@ type ExtrasOptions = {
4822
4899
  /**
4823
4900
  * Options for livecrawling contents
4824
4901
  * @typedef {string} LivecrawlOptions
4902
+ * @deprecated Use `maxAgeHours` instead. Does not guarantee freshly fetched
4903
+ * content. Cannot be combined with `maxAgeHours`.
4825
4904
  */
4826
4905
  type LivecrawlOptions = "never" | "fallback" | "always" | "auto" | "preferred";
4827
4906
  /**
@@ -4917,10 +4996,11 @@ type TextResponse = {
4917
4996
  /**
4918
4997
  * @typedef {Object} HighlightsResponse
4919
4998
  * @property {string[]} highlights - The highlights as an array of strings.
4920
- * @property {number[]} [highlightScores] - The corresponding scores as an array of floats, 0 to 1
4999
+ * @property {number[]} [highlightScores] - Legacy field. The API no longer returns it.
4921
5000
  */
4922
5001
  type HighlightsResponse = {
4923
5002
  highlights: string[];
5003
+ /** @deprecated The API no longer returns this field. */
4924
5004
  highlightScores?: number[];
4925
5005
  };
4926
5006
  /**
@@ -4943,10 +5023,10 @@ type ExtrasResponse = {
4943
5023
  };
4944
5024
  /**
4945
5025
  * @typedef {Object} SubpagesResponse
4946
- * @property {ContentsResultComponent<T extends ContentsOptions>} subpages - The subpages for a result
5026
+ * @property {SearchResult[]} subpages - The subpages for a result, each with the fields of a result and the requested contents.
4947
5027
  */
4948
5028
  type SubpagesResponse<T extends ContentsOptions> = {
4949
- subpages: ContentsResultComponent<T>[];
5029
+ subpages: SearchResult<Omit<T, "subpages">>[];
4950
5030
  };
4951
5031
  type Default<T extends {}, U> = [keyof T] extends [never] ? U : T;
4952
5032
  /**
@@ -5114,7 +5194,7 @@ type Entity = CompanyEntity | PersonEntity;
5114
5194
  * @property {string} url - The URL of the search result.
5115
5195
  * @property {string} [publishedDate] - The estimated creation date of the content.
5116
5196
  * @property {string} [author] - The author of the content, if available.
5117
- * @property {number} [score] - Similarity score between the query/url and the result.
5197
+ * @property {number} [score] - Legacy field. Current search types, including the default "auto", do not return it. Results arrive in relevance order, so keep that order instead of sorting by score.
5118
5198
  * @property {string} id - The temporary ID for the document.
5119
5199
  * @property {string} [image] - A representative image for the content, if any.
5120
5200
  * @property {string} [favicon] - A favicon for the site, if any.
@@ -5234,11 +5314,23 @@ type ContentStatusError = {
5234
5314
  tag?: string;
5235
5315
  httpStatusCode?: number | null;
5236
5316
  };
5317
+ type KnownContentFetchStatus = "success" | "error";
5318
+ /**
5319
+ * Status of the content fetch operation. A value not in
5320
+ * `KnownContentFetchStatus` is kept as a string.
5321
+ */
5322
+ type ContentFetchStatus = KnownContentFetchStatus | (string & {});
5323
+ type KnownContentSource = "cached" | "crawled";
5324
+ /**
5325
+ * Where the returned content was sourced from. A value not in
5326
+ * `KnownContentSource` is kept as a string.
5327
+ */
5328
+ type ContentSource = KnownContentSource | (string & {});
5237
5329
  /** Status information for a requested URL. */
5238
5330
  type Status = {
5239
5331
  id: string;
5240
- status: string;
5241
- source?: string;
5332
+ status: ContentFetchStatus;
5333
+ source?: ContentSource;
5242
5334
  error?: ContentStatusError | null;
5243
5335
  };
5244
5336
  /**
@@ -5292,6 +5384,11 @@ type AnswerStreamChunk = {
5292
5384
  author?: string;
5293
5385
  text?: string;
5294
5386
  }>;
5387
+ /**
5388
+ * The cost breakdown for this request. It arrives once, on a chunk of its
5389
+ * own at the end of the stream.
5390
+ */
5391
+ costDollars?: CostDollars;
5295
5392
  };
5296
5393
  /**
5297
5394
  * One chunk of a `streamSearch` response, with partial text (`content`), new
@@ -5475,7 +5572,7 @@ declare class Exa {
5475
5572
  * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
5476
5573
  */
5477
5574
  search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & BetaOptions & {
5478
- contents: T;
5575
+ contents: T & ExclusiveFreshnessOptions<T>;
5479
5576
  }, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
5480
5577
  /**
5481
5578
  * When no contents option is specified, returns text contents by default.
@@ -5485,7 +5582,9 @@ declare class Exa {
5485
5582
  * @param {RequestOptions} [requestOptions] - Per-call request options (`signal`, `timeout`, `body`, `headers`, `query`).
5486
5583
  * @returns {Promise<SearchResponse<{ text: true }>>} A list of relevant search results with text contents.
5487
5584
  */
5488
- search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions, requestOptions?: RequestOptions): Promise<SearchResponse<{
5585
+ search<C extends ContentsOptions | false | null | undefined = undefined>(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions & {
5586
+ contents?: C & ExclusiveFreshnessOptions<C>;
5587
+ }, requestOptions?: RequestOptions): Promise<SearchResponse<{
5489
5588
  text: true;
5490
5589
  }>>;
5491
5590
  /**
@@ -5493,9 +5592,14 @@ declare class Exa {
5493
5592
  *
5494
5593
  * Each iteration yields a chunk with partial text (`content`) or new citations.
5495
5594
  * When the API returns `warnings` about the request, one chunk after the text
5496
- * carries them.
5595
+ * carries them. The last chunk carries the request's cost breakdown
5596
+ * (`costDollars`).
5497
5597
  * Use this if you'd like to read synthesized search output incrementally.
5498
5598
  * The `lite` search type does not support streaming.
5599
+ *
5600
+ * A search without `outputSchema` has no text to stream. Its stream yields
5601
+ * one chunk with the results as `citations`, then the warnings chunk when
5602
+ * the API returns warnings. Call `search()` for every field of the results.
5499
5603
  * @param {RequestOptions} [requestOptions] - Per-call request options (`signal`, `timeout`, `body`, `headers`, `query`).
5500
5604
  */
5501
5605
  streamSearch<Type extends string = never>(query: string, options?: StreamSearchOptions<Type> & {
@@ -5517,7 +5621,7 @@ declare class Exa {
5517
5621
  * @param {RequestOptions} [requestOptions] - Per-call request options (`signal`, `timeout`, `body`, `headers`, `query`).
5518
5622
  * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
5519
5623
  */
5520
- searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
5624
+ searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T & ExclusiveFreshnessOptions<T>, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
5521
5625
  /**
5522
5626
  * @deprecated Use `search()` instead. There is no direct replacement for URL-based similarity.
5523
5627
  *
@@ -5557,7 +5661,7 @@ declare class Exa {
5557
5661
  * @returns {Promise<SearchResponse<T>>} A list of similar search results with requested contents.
5558
5662
  */
5559
5663
  findSimilar<T extends ContentsOptions>(url: string, options: FindSimilarOptions & {
5560
- contents: T;
5664
+ contents: T & ExclusiveFreshnessOptions<T>;
5561
5665
  }, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
5562
5666
  /**
5563
5667
  * @deprecated Use `search()` instead. There is no direct replacement for URL-based similarity.
@@ -5570,7 +5674,9 @@ declare class Exa {
5570
5674
  * @param {RequestOptions} [requestOptions] - Per-call request options (`signal`, `timeout`, `body`, `headers`, `query`).
5571
5675
  * @returns {Promise<SearchResponse<{ text: true }>>} A list of similar search results with text contents.
5572
5676
  */
5573
- findSimilar(url: string, options: Omit<FindSimilarOptions, "contents">, requestOptions?: RequestOptions): Promise<SearchResponse<{
5677
+ findSimilar<C extends ContentsOptions | false | null | undefined = undefined>(url: string, options: Omit<FindSimilarOptions, "contents"> & {
5678
+ contents?: C & ExclusiveFreshnessOptions<C>;
5679
+ }, requestOptions?: RequestOptions): Promise<SearchResponse<{
5574
5680
  text: true;
5575
5681
  }>>;
5576
5682
  /**
@@ -5586,7 +5692,7 @@ declare class Exa {
5586
5692
  * @param {FindSimilarOptions & T} [options] - Additional options for finding similar links + contents.
5587
5693
  * @returns {Promise<SearchResponse<T>>} A list of similar search results, including requested contents.
5588
5694
  */
5589
- findSimilarAndContents<T extends ContentsOptions>(url: string, options?: FindSimilarOptions & T, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
5695
+ findSimilarAndContents<T extends ContentsOptions>(url: string, options?: FindSimilarOptions & T & ExclusiveFreshnessOptions<T>, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
5590
5696
  /**
5591
5697
  * Retrieves contents of documents based on URLs.
5592
5698
  * @param {string | string[] | SearchResult[]} urls - A URL or array of URLs, or an array of SearchResult objects.
@@ -5594,7 +5700,7 @@ declare class Exa {
5594
5700
  * @param {RequestOptions} [requestOptions] - Per-call request options (`signal`, `timeout`, `body`, `headers`, `query`).
5595
5701
  * @returns {Promise<SearchResponse<T>>} A list of document contents for the requested URLs.
5596
5702
  */
5597
- getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T & BetaOptions & UserIdentifierOptions & TransportRequestOptions, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
5703
+ getContents<T extends ContentsOptions>(urls: string | string[] | SearchResult<T>[], options?: T & ExclusiveFreshnessOptions<T> & BetaOptions & UserIdentifierOptions & TransportRequestOptions, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
5598
5704
  /**
5599
5705
  * Generate an answer with Zod schema for strongly typed output
5600
5706
  */
@@ -5638,6 +5744,7 @@ declare class Exa {
5638
5744
  * Stream an answer as an async generator
5639
5745
  *
5640
5746
  * Each iteration yields a chunk with partial text (`content`) or new citations.
5747
+ * The last chunk carries the request's cost breakdown (`costDollars`).
5641
5748
  * Use this if you'd like to read the answer incrementally, e.g. in a chat UI.
5642
5749
  *
5643
5750
  * Example usage:
@@ -5650,6 +5757,9 @@ declare class Exa {
5650
5757
  * if (chunk.citations) {
5651
5758
  * console.log("\nCitations: ", chunk.citations);
5652
5759
  * }
5760
+ * if (chunk.costDollars) {
5761
+ * console.log("\nCost: ", chunk.costDollars.total);
5762
+ * }
5653
5763
  * }
5654
5764
  * ```
5655
5765
  */
@@ -5661,6 +5771,19 @@ declare class Exa {
5661
5771
  userLocation?: UserLocation;
5662
5772
  } & UserIdentifierOptions & TransportRequestOptions, requestOptions?: RequestOptions): AsyncGenerator<AnswerStreamChunk>;
5663
5773
  private streamChatCompletions;
5774
+ /**
5775
+ * The chunks for a response the API sent whole as JSON instead of streaming
5776
+ * it. The first carries its `results` as `citations`. The rest are the
5777
+ * chunks `payloadChunks` makes of the whole payload: its `warnings`, then
5778
+ * its `costDollars`. A chunk with nothing in it is left out, as in a stream.
5779
+ */
5780
+ private jsonResponseChunks;
5781
+ /**
5782
+ * The chunks one stream payload yields: the chunk `processChunk` makes of
5783
+ * it, then its `costDollars` on a chunk of their own. A chunk with nothing
5784
+ * in it is left out.
5785
+ */
5786
+ private payloadChunks;
5664
5787
  /**
5665
5788
  * Parses one stream payload into a chunk. `warnings` is set only when the
5666
5789
  * payload carries a non-empty `warnings` array, which `/search` sends on its
@@ -5670,4 +5793,4 @@ declare class Exa {
5670
5793
  private parseSSEStream;
5671
5794
  }
5672
5795
 
5673
- 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 ApiWarning, type ApiWarningCode, type ApiWarningContext, type ArticleEntity, type BaseSearchOptions, BetaClient, type BetaOptions, type CompanyEntity, type ContentStatusError, 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 EntityPersonPropertiesEducationHistoryEntry, type EntityPersonPropertiesInstitutionRef, type EntityPersonPropertiesNotableWork, type EntityPersonPropertiesResearch, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaAbortError, type ExaClientOptions, ExaError, type ExaErrorEnvelope, ExaTimeoutError, 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 RequestOptions, 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, SEARCH_OBJECTIVE_TOOL_DESCRIPTION, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchNotice, type SearchNoticeCode, type SearchResponse, type SearchResult, type SearchStreamChunk, type SearchWarning, type SearchWarningCode, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TransportRequestOptions, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type UserIdentifierOptions, type UserLocation, type VerbosityOptions, type WaitUntilCompletedOptions, type WarningsOption, 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 };
5796
+ 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 ApiWarning, type ApiWarningCode, type ApiWarningContext, type ArticleEntity, type BaseSearchOptions, BetaClient, type BetaOptions, type CompanyEntity, type ContentFetchStatus, type ContentSource, type ContentStatusError, 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 EntityPersonPropertiesEducationHistoryEntry, type EntityPersonPropertiesInstitutionRef, type EntityPersonPropertiesNotableWork, type EntityPersonPropertiesResearch, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaAbortError, type ExaClientOptions, ExaError, type ExaErrorEnvelope, ExaTimeoutError, 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 KnownAgentConfidence, type KnownAgentMonitorStatus, type KnownAgentRunStatus, type KnownAgentStopReason, type KnownContentFetchStatus, type KnownContentSource, type KnownSearchMonitorRunFailReason, type KnownSearchMonitorRunStatus, type KnownSearchMonitorStatus, type KnownSearchMonitorWebhookEvent, 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 RequestOptions, 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, SEARCH_OBJECTIVE_TOOL_DESCRIPTION, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchNotice, type SearchNoticeCode, type SearchResponse, type SearchResult, type SearchStreamChunk, type SearchWarning, type SearchWarningCode, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TransportRequestOptions, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type UserIdentifierOptions, type UserLocation, type VerbosityOptions, type WaitUntilCompletedOptions, type WarningsOption, 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 };