exa-js 2.13.0 → 2.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -120,11 +120,10 @@ for await (const chunk of exa.streamAnswer("Explain quantum computing")) {
120
120
  }
121
121
  ```
122
122
 
123
- ## Agent API (Beta)
123
+ ## Agent API
124
124
 
125
125
  ```ts
126
- const run = await exa.beta.agent.runs.create({
127
- betas: ["agent-2026-05-07"],
126
+ const run = await exa.agent.runs.create({
128
127
  query:
129
128
  "Find engineering leaders at AI infrastructure companies that raised a Series A or B in the last 6 months.",
130
129
  outputSchema: {
@@ -147,12 +146,14 @@ const run = await exa.beta.agent.runs.create({
147
146
  required: ["people"],
148
147
  },
149
148
  effort: "auto",
149
+ // Optionally enable Exa Connect data providers for the run.
150
+ dataSources: [{ provider: "financial_datasets" }],
150
151
  });
151
152
 
152
- const completedRun = await exa.beta.agent.runs.pollUntilFinished(run.id, {
153
- betas: ["agent-2026-05-07"],
154
- });
153
+ const completedRun = await exa.agent.runs.pollUntilFinished(run.id);
155
154
  console.log(completedRun.output?.structured);
155
+ // Per-provider tool-call counts and cost for any Exa Connect data sources used.
156
+ console.log(completedRun.usage?.dataSources, completedRun.costDollars?.dataSources);
156
157
  ```
157
158
 
158
159
  ## TypeScript
@@ -176,4 +177,4 @@ Pull requests welcome! For major changes, open an issue first.
176
177
 
177
178
  ## License
178
179
 
179
- [MIT](LICENSE)
180
+ [MIT](LICENSE).
package/dist/index.d.mts CHANGED
@@ -4,14 +4,33 @@ import { ZodSchema } from 'zod';
4
4
  * Types for the Exa Agent API.
5
5
  */
6
6
 
7
+ /**
8
+ * @deprecated Agent API beta header is no longer required for `exa.agent`.
9
+ * Retained for legacy `exa.beta.agent` compatibility.
10
+ */
7
11
  declare const AGENT_BETA_HEADER = "agent-2026-05-07";
8
12
  interface AgentBetaOptions {
9
- betas: string[];
13
+ /**
14
+ * @deprecated Agent API beta header is no longer required for `exa.agent`.
15
+ * Values supplied to `exa.beta.agent` are sent as the `Exa-Beta` header.
16
+ */
17
+ betas?: string[];
10
18
  }
11
19
  type AgentRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
12
20
  type AgentStopReason = "schema_satisfied" | "budget_reached" | "error" | "cancelled";
13
21
  type AgentConfidence = "low" | "medium" | "high";
14
22
  type AgentEffort = "low" | "medium" | "high" | "xhigh" | "auto";
23
+ /**
24
+ * Identifier of an Exa Connect data provider, e.g. `"fiber_ai"`,
25
+ * `"financial_datasets"`, `"similar_web"`, `"baselayer"`, `"affiliate"`,
26
+ * `"particle_news"`, or `"jinko"`.
27
+ */
28
+ type AgentDataSourceProvider = string;
29
+ /** Exa Connect data source to enable for an Agent run. */
30
+ interface AgentDataSource {
31
+ /** Exa Connect data provider to enable for the run. */
32
+ provider: AgentDataSourceProvider;
33
+ }
15
34
  interface AgentInput {
16
35
  data?: Record<string, unknown>[];
17
36
  exclusion?: Record<string, unknown>[];
@@ -40,6 +59,8 @@ interface AgentUsage {
40
59
  searches?: number;
41
60
  emails?: number;
42
61
  phoneNumbers?: number;
62
+ /** Per-provider tool call counts for Exa Connect data sources used during the run. */
63
+ dataSources?: Record<string, number>;
43
64
  [key: string]: unknown;
44
65
  }
45
66
  interface AgentCostDollars {
@@ -48,6 +69,8 @@ interface AgentCostDollars {
48
69
  search?: number;
49
70
  emails?: number;
50
71
  phoneNumbers?: number;
72
+ /** Per-provider cost in dollars for Exa Connect data sources used during the run. */
73
+ dataSources?: Record<string, number>;
51
74
  [key: string]: unknown;
52
75
  }
53
76
  interface AgentError {
@@ -79,7 +102,7 @@ type AgentRunTyped<T> = Omit<AgentRun, "output"> & {
79
102
  structured?: T;
80
103
  }) | null;
81
104
  };
82
- interface ListAgentRunsParams extends AgentBetaOptions {
105
+ interface ListAgentRunsParams {
83
106
  cursor?: string;
84
107
  limit?: number;
85
108
  }
@@ -101,7 +124,7 @@ interface AgentEvent {
101
124
  createdAt?: string;
102
125
  [key: string]: unknown;
103
126
  }
104
- interface ListAgentRunEventsParams extends AgentBetaOptions {
127
+ interface ListAgentRunEventsParams {
105
128
  cursor?: string;
106
129
  limit?: number;
107
130
  }
@@ -112,7 +135,6 @@ interface ListAgentRunEventsResponse {
112
135
  nextCursor: string | null;
113
136
  }
114
137
  interface CreateAgentRunParams {
115
- betas: string[];
116
138
  query: string;
117
139
  systemPrompt?: string;
118
140
  input?: AgentInput;
@@ -120,6 +142,8 @@ interface CreateAgentRunParams {
120
142
  effort?: AgentEffort;
121
143
  previousRunId?: string;
122
144
  metadata?: Record<string, unknown>;
145
+ /** Exa Connect data providers to enable for the run. Each entry enables all of that provider's tools. */
146
+ dataSources?: AgentDataSource[];
123
147
  }
124
148
  type CreateAgentRunParamsTyped<T> = Omit<CreateAgentRunParams, "outputSchema"> & {
125
149
  outputSchema?: T;
@@ -137,8 +161,8 @@ type RequestBody$2 = Record<string, unknown>;
137
161
  declare class AgentBaseClient {
138
162
  protected client: Exa;
139
163
  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>;
164
+ protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<T>;
165
+ protected rawRequest(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<Response>;
142
166
  protected buildPaginationParams(pagination?: ListAgentRunsParams | ListAgentRunEventsParams): QueryParams$3;
143
167
  }
144
168
 
@@ -146,11 +170,12 @@ declare class AgentBaseClient {
146
170
  * Client for the Exa Agent API.
147
171
  */
148
172
 
173
+ type WithBetaOptions<T> = T & AgentBetaOptions;
149
174
  declare class AgentRunEventsClient extends AgentBaseClient {
150
175
  /**
151
176
  * List stored events for an Agent run.
152
177
  */
153
- list(runId: string, options: ListAgentRunEventsParams): Promise<ListAgentRunEventsResponse>;
178
+ list(runId: string, options?: ListAgentRunEventsParams): Promise<ListAgentRunEventsResponse>;
154
179
  }
155
180
  declare class AgentRunsClient extends AgentBaseClient {
156
181
  /**
@@ -171,50 +196,98 @@ declare class AgentRunsClient extends AgentBaseClient {
171
196
  /**
172
197
  * Get an Agent run by ID.
173
198
  */
174
- get(runId: string, options: AgentBetaOptions): Promise<AgentRun>;
199
+ get(runId: string): Promise<AgentRun>;
175
200
  /**
176
201
  * List Agent runs.
177
202
  */
178
- list(options: ListAgentRunsParams): Promise<ListAgentRunsResponse>;
203
+ list(options?: ListAgentRunsParams): Promise<ListAgentRunsResponse>;
179
204
  /**
180
205
  * Iterate through all Agent runs, handling pagination automatically.
181
206
  */
182
- listAll(options: ListAgentRunsParams): AsyncGenerator<AgentRun>;
207
+ listAll(options?: ListAgentRunsParams): AsyncGenerator<AgentRun>;
183
208
  /**
184
209
  * Collect all Agent runs into an array.
185
210
  */
186
- getAll(options: ListAgentRunsParams): Promise<AgentRun[]>;
211
+ getAll(options?: ListAgentRunsParams): Promise<AgentRun[]>;
187
212
  /**
188
213
  * Cancel a queued or running Agent run.
189
214
  */
190
- cancel(runId: string, options: AgentBetaOptions): Promise<AgentRun>;
215
+ cancel(runId: string): Promise<AgentRun>;
191
216
  /**
192
217
  * Delete a stored Agent run.
193
218
  */
194
- delete(runId: string, options: AgentBetaOptions): Promise<DeletedAgentRun>;
219
+ delete(runId: string): Promise<DeletedAgentRun>;
195
220
  /**
196
221
  * Poll an Agent run until it reaches a terminal status.
197
222
  */
198
- pollUntilFinished(runId: string, options: AgentBetaOptions & {
223
+ pollUntilFinished(runId: string, options?: {
199
224
  pollInterval?: number;
200
225
  timeoutMs?: number;
201
226
  }): Promise<AgentRun & {
202
227
  status: "completed" | "failed" | "cancelled";
203
228
  }>;
204
229
  }
205
- declare class AgentBetaClient {
230
+ declare class AgentClient {
231
+ /**
232
+ * @internal
233
+ */
234
+ readonly client: Exa;
206
235
  /**
207
236
  * Client for Agent runs.
208
237
  */
209
238
  runs: AgentRunsClient;
210
239
  constructor(client: Exa);
211
240
  }
241
+ declare class AgentBetaRunEventsClient extends AgentRunEventsClient {
242
+ /**
243
+ * List stored events for an Agent run.
244
+ *
245
+ * @deprecated Use exa.agent.runs.events instead.
246
+ */
247
+ list(runId: string, options?: WithBetaOptions<ListAgentRunEventsParams>): Promise<ListAgentRunEventsResponse>;
248
+ }
249
+ declare class AgentBetaRunsClient extends AgentRunsClient {
250
+ /**
251
+ * @deprecated Use exa.agent.runs.events instead.
252
+ */
253
+ events: AgentBetaRunEventsClient;
254
+ constructor(client: Exa);
255
+ create<T>(params: WithBetaOptions<AgentCreateOptions<T>> & {
256
+ stream: true;
257
+ }): Promise<AsyncGenerator<AgentEvent>>;
258
+ create<T>(params: WithBetaOptions<AgentCreateOptions<T>> & {
259
+ stream?: false;
260
+ }): Promise<AgentRunTyped<T>>;
261
+ create(params: CreateAgentRunParams & AgentBetaOptions): Promise<AgentRun>;
262
+ get(runId: string, options?: AgentBetaOptions): Promise<AgentRun>;
263
+ list(options?: WithBetaOptions<ListAgentRunsParams>): Promise<ListAgentRunsResponse>;
264
+ listAll(options?: WithBetaOptions<ListAgentRunsParams>): AsyncGenerator<AgentRun>;
265
+ getAll(options?: WithBetaOptions<ListAgentRunsParams>): Promise<AgentRun[]>;
266
+ cancel(runId: string, options?: AgentBetaOptions): Promise<AgentRun>;
267
+ delete(runId: string, options?: AgentBetaOptions): Promise<DeletedAgentRun>;
268
+ pollUntilFinished(runId: string, options?: WithBetaOptions<{
269
+ pollInterval?: number;
270
+ timeoutMs?: number;
271
+ }>): Promise<AgentRun & {
272
+ status: "completed" | "failed" | "cancelled";
273
+ }>;
274
+ }
275
+ /**
276
+ * @deprecated Use AgentClient instead.
277
+ */
278
+ declare class AgentBetaClient extends AgentClient {
279
+ /**
280
+ * @deprecated Use exa.agent.runs instead.
281
+ */
282
+ runs: AgentBetaRunsClient;
283
+ constructor(clientOrAgent: Exa | AgentClient);
284
+ }
212
285
  declare class BetaClient {
213
286
  /**
214
- * Beta Agent namespace.
287
+ * @deprecated Use exa.agent instead.
215
288
  */
216
289
  agent: AgentBetaClient;
217
- constructor(client: Exa);
290
+ constructor(clientOrAgent: Exa | AgentClient);
218
291
  }
219
292
 
220
293
  /**
@@ -251,7 +324,11 @@ interface GroundingEntry {
251
324
  }
252
325
  interface SearchMonitorRunOutput {
253
326
  results?: Record<string, unknown>[] | null;
254
- content?: string | null;
327
+ /**
328
+ * Synthesized output. When the monitor is configured with an `outputSchema`,
329
+ * the API returns this as a structured object; otherwise it is a string.
330
+ */
331
+ content?: string | Record<string, unknown> | null;
255
332
  grounding?: GroundingEntry[] | null;
256
333
  }
257
334
  interface SearchMonitor {
@@ -4051,6 +4128,10 @@ declare class Exa {
4051
4128
  * Search Monitors API client
4052
4129
  */
4053
4130
  monitors: SearchMonitorsClient;
4131
+ /**
4132
+ * Agent API client
4133
+ */
4134
+ agent: AgentClient;
4054
4135
  /**
4055
4136
  * Beta API clients
4056
4137
  */
@@ -4291,4 +4372,4 @@ declare class Exa {
4291
4372
  private parseSSEStream;
4292
4373
  }
4293
4374
 
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 };
4375
+ export { AGENT_BETA_HEADER, AgentBetaClient, type AgentBetaOptions, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, 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 };
package/dist/index.d.ts CHANGED
@@ -4,14 +4,33 @@ import { ZodSchema } from 'zod';
4
4
  * Types for the Exa Agent API.
5
5
  */
6
6
 
7
+ /**
8
+ * @deprecated Agent API beta header is no longer required for `exa.agent`.
9
+ * Retained for legacy `exa.beta.agent` compatibility.
10
+ */
7
11
  declare const AGENT_BETA_HEADER = "agent-2026-05-07";
8
12
  interface AgentBetaOptions {
9
- betas: string[];
13
+ /**
14
+ * @deprecated Agent API beta header is no longer required for `exa.agent`.
15
+ * Values supplied to `exa.beta.agent` are sent as the `Exa-Beta` header.
16
+ */
17
+ betas?: string[];
10
18
  }
11
19
  type AgentRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
12
20
  type AgentStopReason = "schema_satisfied" | "budget_reached" | "error" | "cancelled";
13
21
  type AgentConfidence = "low" | "medium" | "high";
14
22
  type AgentEffort = "low" | "medium" | "high" | "xhigh" | "auto";
23
+ /**
24
+ * Identifier of an Exa Connect data provider, e.g. `"fiber_ai"`,
25
+ * `"financial_datasets"`, `"similar_web"`, `"baselayer"`, `"affiliate"`,
26
+ * `"particle_news"`, or `"jinko"`.
27
+ */
28
+ type AgentDataSourceProvider = string;
29
+ /** Exa Connect data source to enable for an Agent run. */
30
+ interface AgentDataSource {
31
+ /** Exa Connect data provider to enable for the run. */
32
+ provider: AgentDataSourceProvider;
33
+ }
15
34
  interface AgentInput {
16
35
  data?: Record<string, unknown>[];
17
36
  exclusion?: Record<string, unknown>[];
@@ -40,6 +59,8 @@ interface AgentUsage {
40
59
  searches?: number;
41
60
  emails?: number;
42
61
  phoneNumbers?: number;
62
+ /** Per-provider tool call counts for Exa Connect data sources used during the run. */
63
+ dataSources?: Record<string, number>;
43
64
  [key: string]: unknown;
44
65
  }
45
66
  interface AgentCostDollars {
@@ -48,6 +69,8 @@ interface AgentCostDollars {
48
69
  search?: number;
49
70
  emails?: number;
50
71
  phoneNumbers?: number;
72
+ /** Per-provider cost in dollars for Exa Connect data sources used during the run. */
73
+ dataSources?: Record<string, number>;
51
74
  [key: string]: unknown;
52
75
  }
53
76
  interface AgentError {
@@ -79,7 +102,7 @@ type AgentRunTyped<T> = Omit<AgentRun, "output"> & {
79
102
  structured?: T;
80
103
  }) | null;
81
104
  };
82
- interface ListAgentRunsParams extends AgentBetaOptions {
105
+ interface ListAgentRunsParams {
83
106
  cursor?: string;
84
107
  limit?: number;
85
108
  }
@@ -101,7 +124,7 @@ interface AgentEvent {
101
124
  createdAt?: string;
102
125
  [key: string]: unknown;
103
126
  }
104
- interface ListAgentRunEventsParams extends AgentBetaOptions {
127
+ interface ListAgentRunEventsParams {
105
128
  cursor?: string;
106
129
  limit?: number;
107
130
  }
@@ -112,7 +135,6 @@ interface ListAgentRunEventsResponse {
112
135
  nextCursor: string | null;
113
136
  }
114
137
  interface CreateAgentRunParams {
115
- betas: string[];
116
138
  query: string;
117
139
  systemPrompt?: string;
118
140
  input?: AgentInput;
@@ -120,6 +142,8 @@ interface CreateAgentRunParams {
120
142
  effort?: AgentEffort;
121
143
  previousRunId?: string;
122
144
  metadata?: Record<string, unknown>;
145
+ /** Exa Connect data providers to enable for the run. Each entry enables all of that provider's tools. */
146
+ dataSources?: AgentDataSource[];
123
147
  }
124
148
  type CreateAgentRunParamsTyped<T> = Omit<CreateAgentRunParams, "outputSchema"> & {
125
149
  outputSchema?: T;
@@ -137,8 +161,8 @@ type RequestBody$2 = Record<string, unknown>;
137
161
  declare class AgentBaseClient {
138
162
  protected client: Exa;
139
163
  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>;
164
+ protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<T>;
165
+ protected rawRequest(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<Response>;
142
166
  protected buildPaginationParams(pagination?: ListAgentRunsParams | ListAgentRunEventsParams): QueryParams$3;
143
167
  }
144
168
 
@@ -146,11 +170,12 @@ declare class AgentBaseClient {
146
170
  * Client for the Exa Agent API.
147
171
  */
148
172
 
173
+ type WithBetaOptions<T> = T & AgentBetaOptions;
149
174
  declare class AgentRunEventsClient extends AgentBaseClient {
150
175
  /**
151
176
  * List stored events for an Agent run.
152
177
  */
153
- list(runId: string, options: ListAgentRunEventsParams): Promise<ListAgentRunEventsResponse>;
178
+ list(runId: string, options?: ListAgentRunEventsParams): Promise<ListAgentRunEventsResponse>;
154
179
  }
155
180
  declare class AgentRunsClient extends AgentBaseClient {
156
181
  /**
@@ -171,50 +196,98 @@ declare class AgentRunsClient extends AgentBaseClient {
171
196
  /**
172
197
  * Get an Agent run by ID.
173
198
  */
174
- get(runId: string, options: AgentBetaOptions): Promise<AgentRun>;
199
+ get(runId: string): Promise<AgentRun>;
175
200
  /**
176
201
  * List Agent runs.
177
202
  */
178
- list(options: ListAgentRunsParams): Promise<ListAgentRunsResponse>;
203
+ list(options?: ListAgentRunsParams): Promise<ListAgentRunsResponse>;
179
204
  /**
180
205
  * Iterate through all Agent runs, handling pagination automatically.
181
206
  */
182
- listAll(options: ListAgentRunsParams): AsyncGenerator<AgentRun>;
207
+ listAll(options?: ListAgentRunsParams): AsyncGenerator<AgentRun>;
183
208
  /**
184
209
  * Collect all Agent runs into an array.
185
210
  */
186
- getAll(options: ListAgentRunsParams): Promise<AgentRun[]>;
211
+ getAll(options?: ListAgentRunsParams): Promise<AgentRun[]>;
187
212
  /**
188
213
  * Cancel a queued or running Agent run.
189
214
  */
190
- cancel(runId: string, options: AgentBetaOptions): Promise<AgentRun>;
215
+ cancel(runId: string): Promise<AgentRun>;
191
216
  /**
192
217
  * Delete a stored Agent run.
193
218
  */
194
- delete(runId: string, options: AgentBetaOptions): Promise<DeletedAgentRun>;
219
+ delete(runId: string): Promise<DeletedAgentRun>;
195
220
  /**
196
221
  * Poll an Agent run until it reaches a terminal status.
197
222
  */
198
- pollUntilFinished(runId: string, options: AgentBetaOptions & {
223
+ pollUntilFinished(runId: string, options?: {
199
224
  pollInterval?: number;
200
225
  timeoutMs?: number;
201
226
  }): Promise<AgentRun & {
202
227
  status: "completed" | "failed" | "cancelled";
203
228
  }>;
204
229
  }
205
- declare class AgentBetaClient {
230
+ declare class AgentClient {
231
+ /**
232
+ * @internal
233
+ */
234
+ readonly client: Exa;
206
235
  /**
207
236
  * Client for Agent runs.
208
237
  */
209
238
  runs: AgentRunsClient;
210
239
  constructor(client: Exa);
211
240
  }
241
+ declare class AgentBetaRunEventsClient extends AgentRunEventsClient {
242
+ /**
243
+ * List stored events for an Agent run.
244
+ *
245
+ * @deprecated Use exa.agent.runs.events instead.
246
+ */
247
+ list(runId: string, options?: WithBetaOptions<ListAgentRunEventsParams>): Promise<ListAgentRunEventsResponse>;
248
+ }
249
+ declare class AgentBetaRunsClient extends AgentRunsClient {
250
+ /**
251
+ * @deprecated Use exa.agent.runs.events instead.
252
+ */
253
+ events: AgentBetaRunEventsClient;
254
+ constructor(client: Exa);
255
+ create<T>(params: WithBetaOptions<AgentCreateOptions<T>> & {
256
+ stream: true;
257
+ }): Promise<AsyncGenerator<AgentEvent>>;
258
+ create<T>(params: WithBetaOptions<AgentCreateOptions<T>> & {
259
+ stream?: false;
260
+ }): Promise<AgentRunTyped<T>>;
261
+ create(params: CreateAgentRunParams & AgentBetaOptions): Promise<AgentRun>;
262
+ get(runId: string, options?: AgentBetaOptions): Promise<AgentRun>;
263
+ list(options?: WithBetaOptions<ListAgentRunsParams>): Promise<ListAgentRunsResponse>;
264
+ listAll(options?: WithBetaOptions<ListAgentRunsParams>): AsyncGenerator<AgentRun>;
265
+ getAll(options?: WithBetaOptions<ListAgentRunsParams>): Promise<AgentRun[]>;
266
+ cancel(runId: string, options?: AgentBetaOptions): Promise<AgentRun>;
267
+ delete(runId: string, options?: AgentBetaOptions): Promise<DeletedAgentRun>;
268
+ pollUntilFinished(runId: string, options?: WithBetaOptions<{
269
+ pollInterval?: number;
270
+ timeoutMs?: number;
271
+ }>): Promise<AgentRun & {
272
+ status: "completed" | "failed" | "cancelled";
273
+ }>;
274
+ }
275
+ /**
276
+ * @deprecated Use AgentClient instead.
277
+ */
278
+ declare class AgentBetaClient extends AgentClient {
279
+ /**
280
+ * @deprecated Use exa.agent.runs instead.
281
+ */
282
+ runs: AgentBetaRunsClient;
283
+ constructor(clientOrAgent: Exa | AgentClient);
284
+ }
212
285
  declare class BetaClient {
213
286
  /**
214
- * Beta Agent namespace.
287
+ * @deprecated Use exa.agent instead.
215
288
  */
216
289
  agent: AgentBetaClient;
217
- constructor(client: Exa);
290
+ constructor(clientOrAgent: Exa | AgentClient);
218
291
  }
219
292
 
220
293
  /**
@@ -251,7 +324,11 @@ interface GroundingEntry {
251
324
  }
252
325
  interface SearchMonitorRunOutput {
253
326
  results?: Record<string, unknown>[] | null;
254
- content?: string | null;
327
+ /**
328
+ * Synthesized output. When the monitor is configured with an `outputSchema`,
329
+ * the API returns this as a structured object; otherwise it is a string.
330
+ */
331
+ content?: string | Record<string, unknown> | null;
255
332
  grounding?: GroundingEntry[] | null;
256
333
  }
257
334
  interface SearchMonitor {
@@ -4051,6 +4128,10 @@ declare class Exa {
4051
4128
  * Search Monitors API client
4052
4129
  */
4053
4130
  monitors: SearchMonitorsClient;
4131
+ /**
4132
+ * Agent API client
4133
+ */
4134
+ agent: AgentClient;
4054
4135
  /**
4055
4136
  * Beta API clients
4056
4137
  */
@@ -4291,4 +4372,4 @@ declare class Exa {
4291
4372
  private parseSSEStream;
4292
4373
  }
4293
4374
 
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 };
4375
+ export { AGENT_BETA_HEADER, AgentBetaClient, type AgentBetaOptions, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, 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 };