exa-js 2.17.0 → 2.18.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
@@ -153,7 +153,10 @@ const run = await exa.agent.runs.create({
153
153
  const completedRun = await exa.agent.runs.pollUntilFinished(run.id);
154
154
  console.log(completedRun.output?.structured);
155
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
+ console.log(
157
+ completedRun.usage?.dataSources,
158
+ completedRun.costDollars?.dataSources
159
+ );
157
160
  ```
158
161
 
159
162
  For Agent Max, use the beta namespace and pass the beta token explicitly:
@@ -162,13 +165,79 @@ For Agent Max, use the beta namespace and pass the beta token explicitly:
162
165
  import { AGENT_MAX_EFFORT_BETA } from "exa-js";
163
166
 
164
167
  const maxRun = await exa.beta.agent.runs.create({
165
- query: "Find all companies building browser automation tools in the United States.",
168
+ query:
169
+ "Find all companies building browser automation tools in the United States.",
166
170
  effort: "max",
167
171
  budget: { maxCostDollars: 10 },
168
172
  betas: [AGENT_MAX_EFFORT_BETA],
169
173
  });
170
174
  ```
171
175
 
176
+ ## Agent Monitors (Beta)
177
+
178
+ Agent Monitors use the beta namespace and require the `AGENT_MONITORS_BETA_HEADER` beta identifier (`agent-monitors-2026-08-04`).
179
+
180
+ An Agent Monitor keeps a table of entities × fields fresh on a cadence: static fields are answered once per entity over the live web, dynamic fields are tracked from news on every refresh.
181
+
182
+ ```ts
183
+ import { AGENT_MONITORS_BETA_HEADER } from "exa-js";
184
+
185
+ const betas = [AGENT_MONITORS_BETA_HEADER];
186
+
187
+ // Create a monitor. Creation is async: it returns with status "creating"
188
+ // and becomes "active" once the first refresh completes.
189
+ const monitor = await exa.beta.agent.monitors.create(
190
+ {
191
+ betas,
192
+ cadence: "7d",
193
+ entities: [
194
+ { name: "Acme Corp", domain: "acme.com" },
195
+ { name: "Globex", domain: "globex.com" },
196
+ ],
197
+ fields: [
198
+ { name: "funding", description: "New funding rounds" }, // dynamic by default
199
+ { name: "ceo", description: "The company's current CEO", mode: "static" },
200
+ ],
201
+ },
202
+ { idempotencyKey: "my-monitor-1" } // safe retries: same key returns the same monitor
203
+ );
204
+
205
+ // Page the monitor's current entities and their contents.
206
+ for await (const {
207
+ entity,
208
+ contents,
209
+ } of exa.beta.agent.monitors.entities.listAll(monitor.id, { betas })) {
210
+ console.log(entity.name, contents);
211
+ }
212
+
213
+ // Follow the content change feed (resume later from the page's nextCursor).
214
+ const changes = await exa.beta.agent.monitors.changes.list(monitor.id, {
215
+ betas,
216
+ since: "2026-01-01T00:00:00Z",
217
+ });
218
+
219
+ // One-shot stateless snapshot of a past news window — no monitor created.
220
+ const snapshot = await exa.beta.agent.monitors.snapshots.createAndWait({
221
+ betas,
222
+ entities: [{ name: "Acme Corp", domain: "acme.com" }],
223
+ fields: [
224
+ { name: "funding", description: "New funding rounds" }, // dynamic by default
225
+ ],
226
+ startDate: "2026-01-01",
227
+ endDate: "2026-01-08",
228
+ });
229
+ console.log(snapshot.data);
230
+
231
+ // Add entities, inspect refresh progress, clean up.
232
+ await exa.beta.agent.monitors.entities.add(monitor.id, {
233
+ betas,
234
+ entities: [{ name: "Initech", domain: "initech.com" }],
235
+ });
236
+ const current = await exa.beta.agent.monitors.get(monitor.id, { betas });
237
+ console.log(current.status, current.refresh, current.usage);
238
+ await exa.beta.agent.monitors.delete(monitor.id, { betas });
239
+ ```
240
+
172
241
  ## TypeScript
173
242
 
174
243
  Full TypeScript support with types for all methods.
package/dist/index.d.mts CHANGED
@@ -167,14 +167,403 @@ type AgentCreateOptions<T = Record<string, unknown>> = CreateAgentRunParamsTyped
167
167
  * Base client for the Exa Agent API.
168
168
  */
169
169
 
170
- type QueryParams$3 = Record<string, string | number | boolean | string[] | undefined>;
171
- type RequestBody$2 = Record<string, unknown>;
170
+ type QueryParams$4 = Record<string, string | number | boolean | string[] | undefined>;
171
+ type RequestBody$3 = Record<string, unknown>;
172
172
  declare class AgentBaseClient {
173
173
  protected client: Exa;
174
174
  constructor(client: Exa);
175
- protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<T>;
176
- protected rawRequest(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<Response>;
177
- protected buildPaginationParams(pagination?: ListAgentRunsParams | ListAgentRunEventsParams): QueryParams$3;
175
+ protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$3, params?: QueryParams$4, headers?: Record<string, string>): Promise<T>;
176
+ protected rawRequest(endpoint: string, method?: string, data?: RequestBody$3, params?: QueryParams$4, headers?: Record<string, string>): Promise<Response>;
177
+ protected buildPaginationParams(pagination?: ListAgentRunsParams | ListAgentRunEventsParams): QueryParams$4;
178
+ }
179
+
180
+ /**
181
+ * Types for the Exa Agent Monitors API (`/agent/monitors`).
182
+ *
183
+ * An Agent Monitor keeps a table of entities × fields fresh: static fields
184
+ * are answered once per entity over the live web, dynamic fields are tracked
185
+ * from news on every refresh, on the monitor's cadence.
186
+ */
187
+ /** Beta identifier required for the Agent Monitors API. */
188
+ declare const AGENT_MONITORS_BETA_HEADER = "agent-monitors-2026-08-04";
189
+ interface AgentMonitorsBetaOptions {
190
+ /** Beta feature identifiers to enable for this request. */
191
+ betas: string[];
192
+ }
193
+ type AgentMonitorStatus = "creating" | "pending_first_refresh" | "active";
194
+ type AgentMonitorFieldMode = "static" | "dynamic";
195
+ /** @deprecated Renamed to {@link AgentMonitorFieldMode}. */
196
+ type AgentMonitorFieldType = AgentMonitorFieldMode;
197
+ /**
198
+ * A field the monitor keeps fresh for every entity. Fields are dynamic
199
+ * (tracked from news on every refresh) unless declared `mode: "static"`
200
+ * (answered once over the live web).
201
+ */
202
+ interface AgentMonitorField {
203
+ id: string;
204
+ name: string;
205
+ description: string;
206
+ mode: AgentMonitorFieldMode;
207
+ /** @deprecated Renamed to `mode`; echoes the same value until removed. */
208
+ type: AgentMonitorFieldMode;
209
+ }
210
+ /** An entity tracked by the monitor. */
211
+ interface AgentMonitorEntity {
212
+ id: string;
213
+ name: string;
214
+ domain?: string;
215
+ canonicalEntityId?: string;
216
+ }
217
+ /** One cell value: a field's current content for an entity. */
218
+ interface AgentMonitorContent {
219
+ value: unknown;
220
+ sourceUrls?: string[];
221
+ updatedAt: string;
222
+ }
223
+ /** Refresh progress on the monitor object; `idle` outside an active refresh. */
224
+ type AgentMonitorRefresh = {
225
+ state: "idle";
226
+ } | {
227
+ state: "running";
228
+ entitiesProcessed: number;
229
+ entitiesTotal: number;
230
+ startedAt: string;
231
+ };
232
+ /** Creation progress on the monitor object; `idle` once the monitor is set up. */
233
+ type AgentMonitorCreation = {
234
+ state: "idle";
235
+ } | {
236
+ state: "running";
237
+ entitiesProcessed: number;
238
+ entitiesTotal: number;
239
+ startedAt: string;
240
+ };
241
+ /** ACU consumption on the monitor object; ACUs are the unit Agent runs bill in. */
242
+ interface AgentMonitorUsage {
243
+ /** Lifetime ACUs consumed by the monitor's refreshes (creation's first refresh included). */
244
+ totalAcus: number;
245
+ /** ACUs consumed by the most recently completed refresh run. */
246
+ lastRefreshAcus: number;
247
+ }
248
+ interface AgentMonitor {
249
+ id: string;
250
+ object: "agent_monitor";
251
+ status: AgentMonitorStatus;
252
+ /** Refresh cadence, e.g. `"12h"` or `"7d"`; also each refresh's lookback window. */
253
+ cadence: string;
254
+ fields: AgentMonitorField[];
255
+ entityCount: number;
256
+ version: number;
257
+ createdAt: string;
258
+ lastRefreshAt: string | null;
259
+ refresh: AgentMonitorRefresh;
260
+ creation: AgentMonitorCreation;
261
+ usage: AgentMonitorUsage;
262
+ sourceRunId?: string;
263
+ }
264
+ /** One entity and its current contents, keyed by field id. */
265
+ interface AgentMonitorEntityView {
266
+ entity: AgentMonitorEntity;
267
+ contents: Record<string, AgentMonitorContent>;
268
+ }
269
+ /**
270
+ * Entity/field references on a change item. `id` is the canonical, stable
271
+ * join key; the name attributes are denormalized for display, resolved as of
272
+ * read time, and absent when the entity/field no longer exists.
273
+ */
274
+ interface AgentMonitorChangeEntity {
275
+ id: string;
276
+ name?: string;
277
+ domain?: string;
278
+ canonicalEntityId?: string;
279
+ }
280
+ interface AgentMonitorChangeField {
281
+ id: string;
282
+ name?: string;
283
+ }
284
+ /** One content change from the monitor's change feed. */
285
+ interface AgentMonitorChange {
286
+ type: "content.upserted";
287
+ entity: AgentMonitorChangeEntity;
288
+ field: AgentMonitorChangeField;
289
+ content: AgentMonitorContent;
290
+ version: number;
291
+ /** ISO-8601 commit time of the change event. */
292
+ createdAt: string;
293
+ }
294
+ /** An entity to track. `domain` anchors entity resolution and must be unique per monitor. */
295
+ interface CreateAgentMonitorEntityParams {
296
+ name: string;
297
+ /** Resolution anchor: entities resolve by first-party or domain-verified evidence. */
298
+ domain: string;
299
+ /** Extra disambiguation context for entity resolution of ambiguous names. */
300
+ description?: string;
301
+ }
302
+ /** A field to keep fresh. Dynamic (the default) unless declared `mode: "static"`. */
303
+ interface CreateAgentMonitorFieldParams {
304
+ name: string;
305
+ description: string;
306
+ mode?: AgentMonitorFieldMode;
307
+ /** @deprecated Renamed to `mode`; declare one spelling, not both. */
308
+ type?: AgentMonitorFieldMode;
309
+ }
310
+ interface CreateAgentMonitorParams {
311
+ /**
312
+ * How often the monitor refreshes, e.g. `"12h"` or `"7d"` (minimum 6h).
313
+ * Also each refresh's news lookback window.
314
+ */
315
+ cadence: string;
316
+ entities: CreateAgentMonitorEntityParams[];
317
+ fields: CreateAgentMonitorFieldParams[];
318
+ }
319
+ interface CreateAgentMonitorOptions {
320
+ /**
321
+ * Sent as the `Idempotency-Key` header. A retried create with the same key
322
+ * returns the monitor the first attempt created (resuming any unfinished
323
+ * entity ingestion) instead of creating a duplicate. Reusing a key with a
324
+ * different body is a 409.
325
+ */
326
+ idempotencyKey?: string;
327
+ }
328
+ interface ListAgentMonitorsParams {
329
+ cursor?: string;
330
+ limit?: number;
331
+ }
332
+ interface ListAgentMonitorEntitiesParams {
333
+ cursor?: string;
334
+ limit?: number;
335
+ /** Only return entities whose contents were updated at or after this ISO-8601 timestamp. */
336
+ since?: string;
337
+ }
338
+ interface ListAgentMonitorChangesParams {
339
+ cursor?: string;
340
+ limit?: number;
341
+ /** Only return changes committed at or after this ISO-8601 timestamp. */
342
+ since?: string;
343
+ }
344
+ interface AddAgentMonitorEntitiesParams {
345
+ entities: CreateAgentMonitorEntityParams[];
346
+ }
347
+ interface ListAgentMonitorsResponse {
348
+ object: "list";
349
+ data: AgentMonitor[];
350
+ hasMore: boolean;
351
+ nextCursor: string | null;
352
+ }
353
+ interface ListAgentMonitorEntitiesResponse {
354
+ object: "list";
355
+ data: AgentMonitorEntityView[];
356
+ hasMore: boolean;
357
+ nextCursor: string | null;
358
+ /** Store head change token — "am I caught up?" display only, NOT the cursor. */
359
+ version: number;
360
+ }
361
+ interface ListAgentMonitorChangesResponse {
362
+ object: "list";
363
+ data: AgentMonitorChange[];
364
+ hasMore: boolean;
365
+ /** Opaque; resume the feed from the last served change. Null when data is empty. */
366
+ nextCursor: string | null;
367
+ /** Store head change token — "am I caught up?" display only, NOT the cursor. */
368
+ version: number;
369
+ }
370
+ interface DeletedAgentMonitor {
371
+ id: string;
372
+ object: "agent_monitor.deleted";
373
+ deleted: true;
374
+ }
375
+ /**
376
+ * Params for a one-shot, stateless snapshot of entities × fields over an
377
+ * explicit past news window — no monitor is created. The window bounds
378
+ * dynamic fields only; static fields return present values answered over the
379
+ * live web, and the result carries a warning when static fields are included.
380
+ */
381
+ interface CreateAgentMonitorSnapshotParams {
382
+ entities: CreateAgentMonitorEntityParams[];
383
+ fields: CreateAgentMonitorFieldParams[];
384
+ /** Start of the news window to snapshot, `YYYY-MM-DD` (UTC). */
385
+ startDate: string;
386
+ /** Hour of startDate the window starts at, 0-23 UTC; omitted means midnight. */
387
+ startHour?: number;
388
+ /** End of the news window to snapshot, `YYYY-MM-DD` (UTC). */
389
+ endDate: string;
390
+ /** Hour of endDate the window ends at, 0-23 UTC; omitted means midnight. */
391
+ endHour?: number;
392
+ }
393
+ /** One entity's snapshot result: populated field values plus the news sources read. */
394
+ interface AgentMonitorSnapshotEntity {
395
+ name: string;
396
+ /** Populated values by field name; fields with no update are absent. */
397
+ fields: Record<string, string>;
398
+ sourceUrls: string[];
399
+ }
400
+ /** The computed body of a finished snapshot, embedded in the job once it completes. */
401
+ interface AgentMonitorSnapshotResult {
402
+ data: AgentMonitorSnapshotEntity[];
403
+ failedEntities?: Array<{
404
+ name: string;
405
+ reason: string;
406
+ }>;
407
+ /** Caveats about how the snapshot was computed, e.g. static fields ignoring the window. */
408
+ warnings?: string[];
409
+ }
410
+ type AgentMonitorSnapshotStatus = "running" | "completed" | "failed";
411
+ /**
412
+ * A snapshot job: `create` returns it as `running`, and `get` polls it to
413
+ * `completed` (result fields present) or `failed`. Jobs expire and read as
414
+ * 404 after `expiresAt`.
415
+ */
416
+ type AgentMonitorSnapshot = {
417
+ id: string;
418
+ object: "agent_monitor.snapshot";
419
+ /** The snapshotted news window, echoed back as normalized ISO-8601 timestamps. */
420
+ startTime: string;
421
+ endTime: string;
422
+ createdAt: string;
423
+ expiresAt: string;
424
+ } & ({
425
+ status: "running";
426
+ } | ({
427
+ status: "completed";
428
+ } & AgentMonitorSnapshotResult) | {
429
+ status: "failed";
430
+ error: string;
431
+ });
432
+ interface AgentMonitorSnapshotWaitOptions {
433
+ pollInterval?: number;
434
+ timeoutMs?: number;
435
+ }
436
+
437
+ /**
438
+ * Base client for the Exa Agent Monitors API.
439
+ */
440
+
441
+ type QueryParams$3 = Record<string, string | number | boolean | string[] | undefined>;
442
+ type RequestBody$2 = Record<string, any>;
443
+ declare class AgentMonitorsBaseClient {
444
+ protected client: Exa;
445
+ constructor(client: Exa);
446
+ protected request<T = unknown>(endpoint: string, betas: string[], method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<T>;
447
+ protected buildPaginationParams(pagination?: ListAgentMonitorsParams | ListAgentMonitorEntitiesParams | ListAgentMonitorChangesParams): QueryParams$3;
448
+ }
449
+
450
+ /**
451
+ * Client for the Exa Agent Monitors API (`/agent/monitors`).
452
+ */
453
+
454
+ type AgentMonitorTerminalSnapshot = AgentMonitorSnapshot & {
455
+ status: "completed" | "failed";
456
+ };
457
+ type AgentMonitorCompletedSnapshot = AgentMonitorSnapshot & {
458
+ status: "completed";
459
+ };
460
+ declare class AgentMonitorSnapshotFailedError extends Error {
461
+ snapshot: AgentMonitorSnapshot & {
462
+ status: "failed";
463
+ };
464
+ constructor(snapshot: AgentMonitorSnapshot & {
465
+ status: "failed";
466
+ });
467
+ }
468
+ declare class AgentMonitorEntitiesClient extends AgentMonitorsBaseClient {
469
+ /**
470
+ * Add entities to an existing Agent Monitor. Added entities are resolved
471
+ * and backfilled shortly after the request completes, then update on the
472
+ * monitor's regular refresh cadence.
473
+ */
474
+ add(monitorId: string, params: AddAgentMonitorEntitiesParams & AgentMonitorsBetaOptions): Promise<AgentMonitor>;
475
+ /**
476
+ * Page an Agent Monitor's current entities and contents, optionally
477
+ * filtered by update time.
478
+ */
479
+ list(monitorId: string, options: ListAgentMonitorEntitiesParams & AgentMonitorsBetaOptions): Promise<ListAgentMonitorEntitiesResponse>;
480
+ /**
481
+ * Iterate through all of a monitor's entities, handling pagination
482
+ * automatically.
483
+ */
484
+ listAll(monitorId: string, options: ListAgentMonitorEntitiesParams & AgentMonitorsBetaOptions): AsyncGenerator<AgentMonitorEntityView>;
485
+ /**
486
+ * Collect all of a monitor's entities into an array.
487
+ */
488
+ getAll(monitorId: string, options: ListAgentMonitorEntitiesParams & AgentMonitorsBetaOptions): Promise<AgentMonitorEntityView[]>;
489
+ }
490
+ declare class AgentMonitorChangesClient extends AgentMonitorsBaseClient {
491
+ /**
492
+ * Page an Agent Monitor's content change feed since a cursor or timestamp.
493
+ */
494
+ list(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): Promise<ListAgentMonitorChangesResponse>;
495
+ /**
496
+ * Iterate through a monitor's change feed, handling pagination
497
+ * automatically.
498
+ */
499
+ listAll(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): AsyncGenerator<AgentMonitorChange>;
500
+ /**
501
+ * Collect a monitor's change feed into an array.
502
+ */
503
+ getAll(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): Promise<AgentMonitorChange[]>;
504
+ }
505
+ declare class AgentMonitorSnapshotsClient extends AgentMonitorsBaseClient {
506
+ /**
507
+ * Start an async, stateless snapshot of entities × fields over an explicit
508
+ * past news window — no monitor is created. Returns a `running` job; poll
509
+ * with `get` (or use `createAndWait`) for the result.
510
+ */
511
+ create(params: CreateAgentMonitorSnapshotParams & AgentMonitorsBetaOptions): Promise<AgentMonitorSnapshot>;
512
+ /**
513
+ * Poll a snapshot job for its status and, once completed, its result.
514
+ * Jobs expire and read as 404 after `expiresAt`.
515
+ */
516
+ get(snapshotId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitorSnapshot>;
517
+ /**
518
+ * Poll a snapshot job until it reaches a terminal status.
519
+ */
520
+ pollUntilFinished(snapshotId: string, options: AgentMonitorSnapshotWaitOptions & AgentMonitorsBetaOptions): Promise<AgentMonitorTerminalSnapshot>;
521
+ /**
522
+ * Start a snapshot and wait for its result. Throws
523
+ * AgentMonitorSnapshotFailedError if the snapshot fails.
524
+ */
525
+ createAndWait(params: CreateAgentMonitorSnapshotParams & AgentMonitorsBetaOptions, options?: AgentMonitorSnapshotWaitOptions): Promise<AgentMonitorCompletedSnapshot>;
526
+ }
527
+ declare class AgentMonitorsClient extends AgentMonitorsBaseClient {
528
+ /**
529
+ * Client for a monitor's entities.
530
+ */
531
+ entities: AgentMonitorEntitiesClient;
532
+ /**
533
+ * Client for a monitor's content change feed.
534
+ */
535
+ changes: AgentMonitorChangesClient;
536
+ /**
537
+ * Client for stateless snapshot jobs.
538
+ */
539
+ snapshots: AgentMonitorSnapshotsClient;
540
+ constructor(client: Exa);
541
+ /**
542
+ * Create an Agent Monitor from its entities, fields, and cadence.
543
+ * Creation is async: the monitor is returned with status `creating` and
544
+ * becomes `active` once its first refresh completes.
545
+ */
546
+ create(params: CreateAgentMonitorParams & AgentMonitorsBetaOptions, options?: CreateAgentMonitorOptions): Promise<AgentMonitor>;
547
+ /**
548
+ * Get an Agent Monitor by ID, including refresh progress.
549
+ */
550
+ get(monitorId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitor>;
551
+ /**
552
+ * List the team's Agent Monitors.
553
+ */
554
+ list(options: ListAgentMonitorsParams & AgentMonitorsBetaOptions): Promise<ListAgentMonitorsResponse>;
555
+ /**
556
+ * Iterate through all Agent Monitors, handling pagination automatically.
557
+ */
558
+ listAll(options: ListAgentMonitorsParams & AgentMonitorsBetaOptions): AsyncGenerator<AgentMonitor>;
559
+ /**
560
+ * Collect all Agent Monitors into an array.
561
+ */
562
+ getAll(options: ListAgentMonitorsParams & AgentMonitorsBetaOptions): Promise<AgentMonitor[]>;
563
+ /**
564
+ * Delete an Agent Monitor and stop its refreshes.
565
+ */
566
+ delete(monitorId: string, options: AgentMonitorsBetaOptions): Promise<DeletedAgentMonitor>;
178
567
  }
179
568
 
180
569
  /**
@@ -310,19 +699,22 @@ declare class AgentBetaRunsClient extends AgentRunsClient {
310
699
  createAndWait<T>(params: WithBetaOptions<Omit<AgentCreateOptions<T>, "stream">>, options?: AgentWaitOptions): Promise<AgentCompletedRunTyped<T>>;
311
700
  createAndWait(params: CreateAgentRunParams & AgentBetaOptions, options?: AgentWaitOptions): Promise<AgentCompletedRun>;
312
701
  }
313
- /**
314
- * @deprecated Use AgentClient instead.
315
- */
702
+ /** Beta Agent API clients. */
316
703
  declare class AgentBetaClient extends AgentClient {
317
704
  /**
318
705
  * @deprecated Use exa.agent.runs instead.
319
706
  */
320
707
  runs: AgentBetaRunsClient;
708
+ /**
709
+ * Beta client for Agent Monitors.
710
+ */
711
+ monitors: AgentMonitorsClient;
321
712
  constructor(clientOrAgent: Exa | AgentClient);
322
713
  }
323
714
  declare class BetaClient {
324
715
  /**
325
- * @deprecated Use exa.agent instead.
716
+ * Beta Agent namespace. Stable Agent runs remain available here for
717
+ * backwards compatibility; beta-only Agent products live here exclusively.
326
718
  */
327
719
  agent: AgentBetaClient;
328
720
  constructor(clientOrAgent: Exa | AgentClient);
@@ -3556,6 +3948,28 @@ declare enum HttpStatusCode {
3556
3948
  InternalServerError = 500,
3557
3949
  ServiceUnavailable = 503
3558
3950
  }
3951
+ /**
3952
+ * Structured fields from the API's error envelope
3953
+ * (e.g. `{ "error": { "type", "code", "message", "detail" }, "requestId" }`).
3954
+ */
3955
+ interface ExaErrorEnvelope {
3956
+ /**
3957
+ * Error category, e.g. "NOT_FOUND", "INVALID_REQUEST", "CONFLICT"
3958
+ */
3959
+ type?: string;
3960
+ /**
3961
+ * Specific error code, e.g. "MONITOR_NOT_FOUND"
3962
+ */
3963
+ code?: string;
3964
+ /**
3965
+ * Additional context, e.g. which validation rule failed
3966
+ */
3967
+ detail?: unknown;
3968
+ /**
3969
+ * Server-side request id for support/debugging
3970
+ */
3971
+ requestId?: string;
3972
+ }
3559
3973
  /**
3560
3974
  * Base error class for all Exa API errors
3561
3975
  */
@@ -3572,14 +3986,31 @@ declare class ExaError extends Error {
3572
3986
  * Path that caused the error (may be undefined for client-side errors)
3573
3987
  */
3574
3988
  path?: string;
3989
+ /**
3990
+ * Error category from the API's error envelope, e.g. "NOT_FOUND"
3991
+ */
3992
+ type?: string;
3993
+ /**
3994
+ * Specific error code from the API's error envelope, e.g. "MONITOR_NOT_FOUND"
3995
+ */
3996
+ code?: string;
3997
+ /**
3998
+ * Additional context from the API's error envelope
3999
+ */
4000
+ detail?: unknown;
4001
+ /**
4002
+ * Server-side request id for support/debugging
4003
+ */
4004
+ requestId?: string;
3575
4005
  /**
3576
4006
  * Create a new ExaError
3577
4007
  * @param message Error message
3578
4008
  * @param statusCode HTTP status code
3579
4009
  * @param timestamp ISO timestamp from API
3580
4010
  * @param path Path that caused the error
4011
+ * @param envelope Structured fields from the API's error envelope
3581
4012
  */
3582
- constructor(message: string, statusCode: number, timestamp?: string, path?: string);
4013
+ constructor(message: string, statusCode: number, timestamp?: string, path?: string, envelope?: ExaErrorEnvelope);
3583
4014
  }
3584
4015
 
3585
4016
  /**
@@ -4412,4 +4843,4 @@ declare class Exa {
4412
4843
  private parseSSEStream;
4413
4844
  }
4414
4845
 
4415
- export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, 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 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 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 };
4846
+ export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, BetaClient, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentMonitorSnapshotParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, 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 };