exa-js 2.17.0 → 2.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -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,418 @@ 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
+ /** The type of a field's cell values. */
196
+ type AgentMonitorFieldValueType = "string" | "number" | "boolean" | "date" | "url" | "email" | "phone";
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
+ /** @deprecated The static/dynamic knob is becoming internal-only. */
207
+ mode: AgentMonitorFieldMode;
208
+ /** The type of the field's cell values. */
209
+ type: AgentMonitorFieldValueType;
210
+ }
211
+ /** An entity tracked by the monitor. */
212
+ interface AgentMonitorEntity {
213
+ id: string;
214
+ name: string;
215
+ domain?: string;
216
+ canonicalEntityId?: string;
217
+ }
218
+ /** One grounding citation for a cell value; the Agent API's citation shape. */
219
+ interface AgentMonitorCitation {
220
+ url: string;
221
+ title?: string;
222
+ note?: string;
223
+ }
224
+ /** One cell value: a field's current content for an entity. */
225
+ interface AgentMonitorContent {
226
+ value: unknown;
227
+ /** Grounding for the value, in the Agent API's citation shape. */
228
+ citations?: AgentMonitorCitation[];
229
+ updatedAt: string;
230
+ }
231
+ /** Refresh progress on the monitor object; `idle` outside an active refresh. */
232
+ type AgentMonitorRefresh = {
233
+ state: "idle";
234
+ } | {
235
+ state: "running";
236
+ entitiesProcessed: number;
237
+ entitiesTotal: number;
238
+ startedAt: string;
239
+ };
240
+ /** Creation progress on the monitor object; `idle` once the monitor is set up. */
241
+ type AgentMonitorCreation = {
242
+ state: "idle";
243
+ } | {
244
+ state: "running";
245
+ entitiesProcessed: number;
246
+ entitiesTotal: number;
247
+ startedAt: string;
248
+ };
249
+ /** ACU consumption on the monitor object; ACUs are the unit Agent runs bill in. */
250
+ interface AgentMonitorUsage {
251
+ /** Lifetime ACUs consumed by the monitor's refreshes (creation's first refresh included). */
252
+ totalAcus: number;
253
+ /** ACUs consumed by the most recently completed refresh run. */
254
+ lastRefreshAcus: number;
255
+ }
256
+ interface AgentMonitor {
257
+ id: string;
258
+ object: "agent_monitor";
259
+ status: AgentMonitorStatus;
260
+ /** Refresh cadence, e.g. `"12h"` or `"7d"`; also each refresh's lookback window. */
261
+ cadence: string;
262
+ fields: AgentMonitorField[];
263
+ entityCount: number;
264
+ version: number;
265
+ createdAt: string;
266
+ lastRefreshAt: string | null;
267
+ refresh: AgentMonitorRefresh;
268
+ creation: AgentMonitorCreation;
269
+ usage: AgentMonitorUsage;
270
+ sourceRunId?: string;
271
+ }
272
+ /** One entity and its current contents, keyed by field id. */
273
+ interface AgentMonitorEntityView {
274
+ entity: AgentMonitorEntity;
275
+ contents: Record<string, AgentMonitorContent>;
276
+ }
277
+ /**
278
+ * Entity/field references on a change item. `id` is the canonical, stable
279
+ * join key; the name attributes are denormalized for display, resolved as of
280
+ * read time, and absent when the entity/field no longer exists.
281
+ */
282
+ interface AgentMonitorChangeEntity {
283
+ id: string;
284
+ name?: string;
285
+ domain?: string;
286
+ canonicalEntityId?: string;
287
+ }
288
+ interface AgentMonitorChangeField {
289
+ id: string;
290
+ name?: string;
291
+ }
292
+ /** One content change from the monitor's change feed. */
293
+ interface AgentMonitorChange {
294
+ type: "content.upserted";
295
+ entity: AgentMonitorChangeEntity;
296
+ field: AgentMonitorChangeField;
297
+ content: AgentMonitorContent;
298
+ version: number;
299
+ /** ISO-8601 commit time of the change event. */
300
+ createdAt: string;
301
+ }
302
+ /** An entity to track. `domain` anchors entity resolution and must be unique per monitor. */
303
+ interface CreateAgentMonitorEntityParams {
304
+ name: string;
305
+ /** Resolution anchor: entities resolve by first-party or domain-verified evidence. */
306
+ domain: string;
307
+ /** Extra disambiguation context for entity resolution of ambiguous names. */
308
+ description?: string;
309
+ }
310
+ /** A field to keep fresh. Dynamic (the default) unless declared `mode: "static"`. */
311
+ interface CreateAgentMonitorFieldParams {
312
+ name: string;
313
+ description: string;
314
+ /**
315
+ * The type of the field's cell values; defaults to `"string"`. Cell values
316
+ * are normalized to the declared type best-effort on write, never rejected
317
+ * — but declaring an unsupported type (e.g. `"object"`) is a 400.
318
+ * `"static"`/`"dynamic"` are accepted as deprecated aliases of `mode`;
319
+ * declaring both spellings is a 400.
320
+ */
321
+ type?: AgentMonitorFieldValueType | AgentMonitorFieldMode;
322
+ /** @deprecated The static/dynamic knob is becoming internal-only. */
323
+ mode?: AgentMonitorFieldMode;
324
+ }
325
+ interface CreateAgentMonitorParams {
326
+ /**
327
+ * How often the monitor refreshes, e.g. `"12h"` or `"7d"` (minimum 6h).
328
+ * Also each refresh's news lookback window.
329
+ */
330
+ cadence: string;
331
+ entities: CreateAgentMonitorEntityParams[];
332
+ fields: CreateAgentMonitorFieldParams[];
333
+ }
334
+ interface CreateAgentMonitorOptions {
335
+ /**
336
+ * Sent as the `Idempotency-Key` header. A retried create with the same key
337
+ * returns the monitor the first attempt created (resuming any unfinished
338
+ * entity ingestion) instead of creating a duplicate. Reusing a key with a
339
+ * different body is a 409.
340
+ */
341
+ idempotencyKey?: string;
342
+ }
343
+ interface ListAgentMonitorsParams {
344
+ cursor?: string;
345
+ limit?: number;
346
+ }
347
+ interface ListAgentMonitorEntitiesParams {
348
+ cursor?: string;
349
+ limit?: number;
350
+ /** Only return entities whose contents were updated at or after this ISO-8601 timestamp. */
351
+ since?: string;
352
+ }
353
+ interface ListAgentMonitorChangesParams {
354
+ cursor?: string;
355
+ limit?: number;
356
+ /** Only return changes committed at or after this ISO-8601 timestamp. */
357
+ since?: string;
358
+ }
359
+ interface AddAgentMonitorEntitiesParams {
360
+ entities: CreateAgentMonitorEntityParams[];
361
+ }
362
+ interface ListAgentMonitorsResponse {
363
+ object: "list";
364
+ data: AgentMonitor[];
365
+ hasMore: boolean;
366
+ nextCursor: string | null;
367
+ }
368
+ interface ListAgentMonitorEntitiesResponse {
369
+ object: "list";
370
+ data: AgentMonitorEntityView[];
371
+ hasMore: boolean;
372
+ nextCursor: string | null;
373
+ /** Store head change token — "am I caught up?" display only, NOT the cursor. */
374
+ version: number;
375
+ }
376
+ interface ListAgentMonitorChangesResponse {
377
+ object: "list";
378
+ data: AgentMonitorChange[];
379
+ hasMore: boolean;
380
+ /** Opaque; resume the feed from the last served change. Null when data is empty. */
381
+ nextCursor: string | null;
382
+ /** Store head change token — "am I caught up?" display only, NOT the cursor. */
383
+ version: number;
384
+ }
385
+ interface DeletedAgentMonitor {
386
+ id: string;
387
+ object: "agent_monitor.deleted";
388
+ deleted: true;
389
+ }
390
+ /**
391
+ * Params for a one-shot, stateless snapshot of entities × fields over an
392
+ * explicit past news window — no monitor is created. The window bounds
393
+ * dynamic fields only; static fields return present values answered over the
394
+ * live web, and the result carries a warning when static fields are included.
395
+ */
396
+ interface CreateAgentMonitorSnapshotParams {
397
+ entities: CreateAgentMonitorEntityParams[];
398
+ fields: CreateAgentMonitorFieldParams[];
399
+ /** Start of the news window to snapshot, `YYYY-MM-DD` (UTC). */
400
+ startDate: string;
401
+ /** Hour of startDate the window starts at, 0-23 UTC; omitted means midnight. */
402
+ startHour?: number;
403
+ /** End of the news window to snapshot, `YYYY-MM-DD` (UTC). */
404
+ endDate: string;
405
+ /** Hour of endDate the window ends at, 0-23 UTC; omitted means midnight. */
406
+ endHour?: number;
407
+ }
408
+ /** One entity's snapshot result: populated field values plus the news sources read. */
409
+ interface AgentMonitorSnapshotEntity {
410
+ name: string;
411
+ /** Populated values by field name; fields with no update are absent. */
412
+ fields: Record<string, string>;
413
+ sourceUrls: string[];
414
+ }
415
+ /** The computed body of a finished snapshot, embedded in the job once it completes. */
416
+ interface AgentMonitorSnapshotResult {
417
+ data: AgentMonitorSnapshotEntity[];
418
+ failedEntities?: Array<{
419
+ name: string;
420
+ reason: string;
421
+ }>;
422
+ /** Caveats about how the snapshot was computed, e.g. static fields ignoring the window. */
423
+ warnings?: string[];
424
+ }
425
+ type AgentMonitorSnapshotStatus = "running" | "completed" | "failed";
426
+ /**
427
+ * A snapshot job: `create` returns it as `running`, and `get` polls it to
428
+ * `completed` (result fields present) or `failed`. Jobs expire and read as
429
+ * 404 after `expiresAt`.
430
+ */
431
+ type AgentMonitorSnapshot = {
432
+ id: string;
433
+ object: "agent_monitor.snapshot";
434
+ /** The snapshotted news window, echoed back as normalized ISO-8601 timestamps. */
435
+ startTime: string;
436
+ endTime: string;
437
+ createdAt: string;
438
+ expiresAt: string;
439
+ } & ({
440
+ status: "running";
441
+ } | ({
442
+ status: "completed";
443
+ } & AgentMonitorSnapshotResult) | {
444
+ status: "failed";
445
+ error: string;
446
+ });
447
+ interface AgentMonitorSnapshotWaitOptions {
448
+ pollInterval?: number;
449
+ timeoutMs?: number;
450
+ }
451
+
452
+ /**
453
+ * Base client for the Exa Agent Monitors API.
454
+ */
455
+
456
+ type QueryParams$3 = Record<string, string | number | boolean | string[] | undefined>;
457
+ type RequestBody$2 = Record<string, any>;
458
+ declare class AgentMonitorsBaseClient {
459
+ protected client: Exa;
460
+ constructor(client: Exa);
461
+ protected request<T = unknown>(endpoint: string, betas: string[], method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<T>;
462
+ protected buildPaginationParams(pagination?: ListAgentMonitorsParams | ListAgentMonitorEntitiesParams | ListAgentMonitorChangesParams): QueryParams$3;
463
+ }
464
+
465
+ /**
466
+ * Client for the Exa Agent Monitors API (`/agent/monitors`).
467
+ */
468
+
469
+ type AgentMonitorTerminalSnapshot = AgentMonitorSnapshot & {
470
+ status: "completed" | "failed";
471
+ };
472
+ type AgentMonitorCompletedSnapshot = AgentMonitorSnapshot & {
473
+ status: "completed";
474
+ };
475
+ declare class AgentMonitorSnapshotFailedError extends Error {
476
+ snapshot: AgentMonitorSnapshot & {
477
+ status: "failed";
478
+ };
479
+ constructor(snapshot: AgentMonitorSnapshot & {
480
+ status: "failed";
481
+ });
482
+ }
483
+ declare class AgentMonitorEntitiesClient extends AgentMonitorsBaseClient {
484
+ /**
485
+ * Add entities to an existing Agent Monitor. Added entities are resolved
486
+ * and backfilled shortly after the request completes, then update on the
487
+ * monitor's regular refresh cadence.
488
+ */
489
+ add(monitorId: string, params: AddAgentMonitorEntitiesParams & AgentMonitorsBetaOptions): Promise<AgentMonitor>;
490
+ /**
491
+ * Page an Agent Monitor's current entities and contents, optionally
492
+ * filtered by update time.
493
+ */
494
+ list(monitorId: string, options: ListAgentMonitorEntitiesParams & AgentMonitorsBetaOptions): Promise<ListAgentMonitorEntitiesResponse>;
495
+ /**
496
+ * Iterate through all of a monitor's entities, handling pagination
497
+ * automatically.
498
+ */
499
+ listAll(monitorId: string, options: ListAgentMonitorEntitiesParams & AgentMonitorsBetaOptions): AsyncGenerator<AgentMonitorEntityView>;
500
+ /**
501
+ * Collect all of a monitor's entities into an array.
502
+ */
503
+ getAll(monitorId: string, options: ListAgentMonitorEntitiesParams & AgentMonitorsBetaOptions): Promise<AgentMonitorEntityView[]>;
504
+ }
505
+ declare class AgentMonitorChangesClient extends AgentMonitorsBaseClient {
506
+ /**
507
+ * Page an Agent Monitor's content change feed since a cursor or timestamp.
508
+ */
509
+ list(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): Promise<ListAgentMonitorChangesResponse>;
510
+ /**
511
+ * Iterate through a monitor's change feed, handling pagination
512
+ * automatically.
513
+ */
514
+ listAll(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): AsyncGenerator<AgentMonitorChange>;
515
+ /**
516
+ * Collect a monitor's change feed into an array.
517
+ */
518
+ getAll(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): Promise<AgentMonitorChange[]>;
519
+ }
520
+ declare class AgentMonitorSnapshotsClient extends AgentMonitorsBaseClient {
521
+ /**
522
+ * Start an async, stateless snapshot of entities × fields over an explicit
523
+ * past news window — no monitor is created. Returns a `running` job; poll
524
+ * with `get` (or use `createAndWait`) for the result.
525
+ */
526
+ create(params: CreateAgentMonitorSnapshotParams & AgentMonitorsBetaOptions): Promise<AgentMonitorSnapshot>;
527
+ /**
528
+ * Poll a snapshot job for its status and, once completed, its result.
529
+ * Jobs expire and read as 404 after `expiresAt`.
530
+ */
531
+ get(snapshotId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitorSnapshot>;
532
+ /**
533
+ * Poll a snapshot job until it reaches a terminal status.
534
+ */
535
+ pollUntilFinished(snapshotId: string, options: AgentMonitorSnapshotWaitOptions & AgentMonitorsBetaOptions): Promise<AgentMonitorTerminalSnapshot>;
536
+ /**
537
+ * Start a snapshot and wait for its result. Throws
538
+ * AgentMonitorSnapshotFailedError if the snapshot fails.
539
+ */
540
+ createAndWait(params: CreateAgentMonitorSnapshotParams & AgentMonitorsBetaOptions, options?: AgentMonitorSnapshotWaitOptions): Promise<AgentMonitorCompletedSnapshot>;
541
+ }
542
+ declare class AgentMonitorsClient extends AgentMonitorsBaseClient {
543
+ /**
544
+ * Client for a monitor's entities.
545
+ */
546
+ entities: AgentMonitorEntitiesClient;
547
+ /**
548
+ * Client for a monitor's content change feed.
549
+ */
550
+ changes: AgentMonitorChangesClient;
551
+ /**
552
+ * Client for stateless snapshot jobs.
553
+ */
554
+ snapshots: AgentMonitorSnapshotsClient;
555
+ constructor(client: Exa);
556
+ /**
557
+ * Create an Agent Monitor from its entities, fields, and cadence.
558
+ * Creation is async: the monitor is returned with status `creating` and
559
+ * becomes `active` once its first refresh completes.
560
+ */
561
+ create(params: CreateAgentMonitorParams & AgentMonitorsBetaOptions, options?: CreateAgentMonitorOptions): Promise<AgentMonitor>;
562
+ /**
563
+ * Get an Agent Monitor by ID, including refresh progress.
564
+ */
565
+ get(monitorId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitor>;
566
+ /**
567
+ * List the team's Agent Monitors.
568
+ */
569
+ list(options: ListAgentMonitorsParams & AgentMonitorsBetaOptions): Promise<ListAgentMonitorsResponse>;
570
+ /**
571
+ * Iterate through all Agent Monitors, handling pagination automatically.
572
+ */
573
+ listAll(options: ListAgentMonitorsParams & AgentMonitorsBetaOptions): AsyncGenerator<AgentMonitor>;
574
+ /**
575
+ * Collect all Agent Monitors into an array.
576
+ */
577
+ getAll(options: ListAgentMonitorsParams & AgentMonitorsBetaOptions): Promise<AgentMonitor[]>;
578
+ /**
579
+ * Delete an Agent Monitor and stop its refreshes.
580
+ */
581
+ delete(monitorId: string, options: AgentMonitorsBetaOptions): Promise<DeletedAgentMonitor>;
178
582
  }
179
583
 
180
584
  /**
@@ -310,19 +714,22 @@ declare class AgentBetaRunsClient extends AgentRunsClient {
310
714
  createAndWait<T>(params: WithBetaOptions<Omit<AgentCreateOptions<T>, "stream">>, options?: AgentWaitOptions): Promise<AgentCompletedRunTyped<T>>;
311
715
  createAndWait(params: CreateAgentRunParams & AgentBetaOptions, options?: AgentWaitOptions): Promise<AgentCompletedRun>;
312
716
  }
313
- /**
314
- * @deprecated Use AgentClient instead.
315
- */
717
+ /** Beta Agent API clients. */
316
718
  declare class AgentBetaClient extends AgentClient {
317
719
  /**
318
720
  * @deprecated Use exa.agent.runs instead.
319
721
  */
320
722
  runs: AgentBetaRunsClient;
723
+ /**
724
+ * Beta client for Agent Monitors.
725
+ */
726
+ monitors: AgentMonitorsClient;
321
727
  constructor(clientOrAgent: Exa | AgentClient);
322
728
  }
323
729
  declare class BetaClient {
324
730
  /**
325
- * @deprecated Use exa.agent instead.
731
+ * Beta Agent namespace. Stable Agent runs remain available here for
732
+ * backwards compatibility; beta-only Agent products live here exclusively.
326
733
  */
327
734
  agent: AgentBetaClient;
328
735
  constructor(clientOrAgent: Exa | AgentClient);
@@ -3556,6 +3963,28 @@ declare enum HttpStatusCode {
3556
3963
  InternalServerError = 500,
3557
3964
  ServiceUnavailable = 503
3558
3965
  }
3966
+ /**
3967
+ * Structured fields from the API's error envelope
3968
+ * (e.g. `{ "error": { "type", "code", "message", "detail" }, "requestId" }`).
3969
+ */
3970
+ interface ExaErrorEnvelope {
3971
+ /**
3972
+ * Error category, e.g. "NOT_FOUND", "INVALID_REQUEST", "CONFLICT"
3973
+ */
3974
+ type?: string;
3975
+ /**
3976
+ * Specific error code, e.g. "MONITOR_NOT_FOUND"
3977
+ */
3978
+ code?: string;
3979
+ /**
3980
+ * Additional context, e.g. which validation rule failed
3981
+ */
3982
+ detail?: unknown;
3983
+ /**
3984
+ * Server-side request id for support/debugging
3985
+ */
3986
+ requestId?: string;
3987
+ }
3559
3988
  /**
3560
3989
  * Base error class for all Exa API errors
3561
3990
  */
@@ -3572,14 +4001,31 @@ declare class ExaError extends Error {
3572
4001
  * Path that caused the error (may be undefined for client-side errors)
3573
4002
  */
3574
4003
  path?: string;
4004
+ /**
4005
+ * Error category from the API's error envelope, e.g. "NOT_FOUND"
4006
+ */
4007
+ type?: string;
4008
+ /**
4009
+ * Specific error code from the API's error envelope, e.g. "MONITOR_NOT_FOUND"
4010
+ */
4011
+ code?: string;
4012
+ /**
4013
+ * Additional context from the API's error envelope
4014
+ */
4015
+ detail?: unknown;
4016
+ /**
4017
+ * Server-side request id for support/debugging
4018
+ */
4019
+ requestId?: string;
3575
4020
  /**
3576
4021
  * Create a new ExaError
3577
4022
  * @param message Error message
3578
4023
  * @param statusCode HTTP status code
3579
4024
  * @param timestamp ISO timestamp from API
3580
4025
  * @param path Path that caused the error
4026
+ * @param envelope Structured fields from the API's error envelope
3581
4027
  */
3582
- constructor(message: string, statusCode: number, timestamp?: string, path?: string);
4028
+ constructor(message: string, statusCode: number, timestamp?: string, path?: string, envelope?: ExaErrorEnvelope);
3583
4029
  }
3584
4030
 
3585
4031
  /**
@@ -4412,4 +4858,4 @@ declare class Exa {
4412
4858
  private parseSSEStream;
4413
4859
  }
4414
4860
 
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 };
4861
+ export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorSnapshot, type AgentMonitorSnapshotEntity, AgentMonitorSnapshotFailedError, type AgentMonitorSnapshotResult, type AgentMonitorSnapshotStatus, type AgentMonitorSnapshotWaitOptions, AgentMonitorSnapshotsClient, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type 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 };