exa-js 2.7.0 → 2.10.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
@@ -25,17 +25,7 @@ const result = await exa.search(
25
25
  {
26
26
  type: "auto",
27
27
  contents: {
28
- text: true
29
- }
30
- }
31
- );
32
-
33
- // Find similar pages
34
- const result = await exa.findSimilar(
35
- "https://paulgraham.com/greatwork.html",
36
- {
37
- contents: {
38
- text: true
28
+ highlights: true
39
29
  }
40
30
  }
41
31
  );
@@ -54,7 +44,7 @@ const result = await exa.search("interesting articles about space", {
54
44
  includeDomains: ["nasa.gov", "space.com"],
55
45
  startPublishedDate: "2024-01-01",
56
46
  contents: {
57
- text: true
47
+ highlights: true
58
48
  }
59
49
  });
60
50
  ```
@@ -62,6 +52,7 @@ const result = await exa.search("interesting articles about space", {
62
52
  ```ts
63
53
  const deepResult = await exa.search("Who leads OpenAI's safety team?", {
64
54
  type: "deep",
55
+ systemPrompt: "Prefer official sources and avoid duplicate results",
65
56
  outputSchema: {
66
57
  type: "object",
67
58
  properties: {
@@ -80,6 +71,8 @@ Deep `outputSchema` modes:
80
71
  - `type: "text"`: return plain text in `output.content` (optionally guided by `description`)
81
72
  - `type: "object"`: return structured JSON in `output.content`
82
73
 
74
+ Deep search also supports `systemPrompt` to guide both the search process and the final returned result, for example by preferring certain sources, emphasizing novel findings, avoiding duplicates, or constraining output style.
75
+
83
76
  For `type: "object"`, deep search currently enforces:
84
77
  - max nesting depth: `2`
85
78
  - max total properties: `10`
@@ -87,37 +80,19 @@ For `type: "object"`, deep search currently enforces:
87
80
  Deep search variants:
88
81
  - `deep`: light mode
89
82
  - `deep-reasoning`: base reasoning mode
90
- - `deep-max`: max-effort mode
91
83
 
92
84
  ## Contents
93
85
 
94
86
  Get clean text, highlights, or summaries from any URL.
95
87
 
96
88
  ```ts
97
- const { results } = await exa.getContents(["https://openai.com/research"], {
89
+ const { results } = await exa.getContents(["https://docs.exa.ai"], {
98
90
  text: true,
99
91
  highlights: true,
100
92
  summary: true,
101
93
  });
102
94
  ```
103
95
 
104
- ## Find Similar
105
-
106
- Discover pages similar to a given URL.
107
-
108
- ```ts
109
- const result = await exa.findSimilar(
110
- "https://paulgraham.com/greatwork.html",
111
- {
112
- numResults: 10,
113
- excludeSourceDomain: true,
114
- contents: {
115
- text: true
116
- }
117
- }
118
- );
119
- ```
120
-
121
96
  ## Answer
122
97
 
123
98
  ```ts
@@ -133,24 +108,6 @@ for await (const chunk of exa.streamAnswer("Explain quantum computing")) {
133
108
  }
134
109
  ```
135
110
 
136
- ## Research
137
-
138
- Run autonomous research tasks that return structured data.
139
-
140
- ```ts
141
- const { researchId } = await exa.research.create({
142
- instructions: "Find the top 5 AI startups founded in 2024",
143
- outputSchema: {
144
- type: "object",
145
- properties: {
146
- startups: { type: "array", items: { type: "string" } },
147
- },
148
- },
149
- });
150
-
151
- const result = await exa.research.pollUntilFinished(researchId);
152
- ```
153
-
154
111
  ## TypeScript
155
112
 
156
113
  Full TypeScript support with types for all methods.
package/dist/index.d.mts CHANGED
@@ -1,5 +1,222 @@
1
1
  import { ZodSchema } from 'zod';
2
2
 
3
+ /**
4
+ * Types for the Search Monitors API
5
+ */
6
+
7
+ type SearchMonitorStatus = "active" | "paused" | "disabled";
8
+ type SearchMonitorRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
9
+ type SearchMonitorRunFailReason = "api_key_invalid" | "insufficient_credits" | "invalid_params" | "rate_limited" | "search_unavailable" | "search_failed" | "internal_error";
10
+ type SearchMonitorWebhookEvent = "monitor.created" | "monitor.updated" | "monitor.deleted" | "monitor.run.created" | "monitor.run.completed";
11
+ interface SearchMonitorSearch {
12
+ query: string;
13
+ numResults?: number;
14
+ includeDomains?: string[];
15
+ excludeDomains?: string[];
16
+ contents?: ContentsOptions;
17
+ }
18
+ interface SearchMonitorTrigger {
19
+ type: "cron";
20
+ expression: string;
21
+ timezone?: string;
22
+ }
23
+ interface SearchMonitorWebhook {
24
+ url: string;
25
+ events?: SearchMonitorWebhookEvent[];
26
+ }
27
+ interface GroundingCitation {
28
+ url: string;
29
+ title: string;
30
+ }
31
+ interface GroundingEntry {
32
+ field: string;
33
+ citations: GroundingCitation[];
34
+ confidence: "low" | "medium" | "high";
35
+ }
36
+ interface SearchMonitorRunOutput {
37
+ results?: Record<string, unknown>[] | null;
38
+ content?: string | null;
39
+ grounding?: GroundingEntry[] | null;
40
+ }
41
+ interface SearchMonitor {
42
+ id: string;
43
+ name: string | null;
44
+ status: SearchMonitorStatus;
45
+ search: SearchMonitorSearch;
46
+ trigger: SearchMonitorTrigger | null;
47
+ outputSchema: Record<string, unknown> | null;
48
+ metadata: Record<string, string> | null;
49
+ webhook: SearchMonitorWebhook;
50
+ nextRunAt: string | null;
51
+ createdAt: string;
52
+ updatedAt: string;
53
+ }
54
+ interface CreateSearchMonitorResponse extends SearchMonitor {
55
+ webhookSecret: string;
56
+ }
57
+ interface SearchMonitorRun {
58
+ id: string;
59
+ monitorId: string;
60
+ status: SearchMonitorRunStatus;
61
+ output: SearchMonitorRunOutput | null;
62
+ failReason: SearchMonitorRunFailReason | null;
63
+ startedAt: string | null;
64
+ completedAt: string | null;
65
+ failedAt: string | null;
66
+ cancelledAt: string | null;
67
+ durationMs: number | null;
68
+ createdAt: string;
69
+ updatedAt: string;
70
+ }
71
+ interface CreateSearchMonitorParams {
72
+ name?: string;
73
+ search: SearchMonitorSearch;
74
+ trigger?: SearchMonitorTrigger;
75
+ outputSchema?: Record<string, unknown>;
76
+ metadata?: Record<string, string>;
77
+ webhook: SearchMonitorWebhook;
78
+ }
79
+ interface UpdateSearchMonitorParams {
80
+ name?: string | null;
81
+ status?: SearchMonitorStatus;
82
+ search?: SearchMonitorSearch;
83
+ trigger?: SearchMonitorTrigger | null;
84
+ outputSchema?: Record<string, unknown> | null;
85
+ metadata?: Record<string, string> | null;
86
+ webhook?: SearchMonitorWebhook;
87
+ }
88
+ interface ListSearchMonitorsParams {
89
+ cursor?: string;
90
+ limit?: number;
91
+ status?: SearchMonitorStatus;
92
+ }
93
+ interface ListSearchMonitorRunsParams {
94
+ cursor?: string;
95
+ limit?: number;
96
+ }
97
+ interface ListSearchMonitorsResponse {
98
+ data: SearchMonitor[];
99
+ hasMore: boolean;
100
+ nextCursor: string | null;
101
+ }
102
+ interface ListSearchMonitorRunsResponse {
103
+ data: SearchMonitorRun[];
104
+ hasMore: boolean;
105
+ nextCursor: string | null;
106
+ }
107
+ interface TriggerSearchMonitorResponse {
108
+ triggered: boolean;
109
+ }
110
+
111
+ /**
112
+ * Base client for Search Monitors API
113
+ */
114
+
115
+ type QueryParams$2 = Record<string, string | number | boolean | string[] | undefined>;
116
+ declare class SearchMonitorsBaseClient {
117
+ protected client: Exa;
118
+ constructor(client: Exa);
119
+ protected request<T = unknown>(endpoint: string, method?: string, data?: Record<string, any>, params?: QueryParams$2): Promise<T>;
120
+ protected buildPaginationParams(pagination?: ListSearchMonitorsParams | ListSearchMonitorRunsParams): QueryParams$2;
121
+ }
122
+
123
+ /**
124
+ * Client for the Search Monitors API
125
+ */
126
+
127
+ /**
128
+ * Client for managing Search Monitor Runs
129
+ */
130
+ declare class SearchMonitorRunsClient extends SearchMonitorsBaseClient {
131
+ /**
132
+ * List all runs for a Search Monitor
133
+ * @param monitorId The ID of the Search Monitor
134
+ * @param options Pagination options
135
+ * @returns The list of Search Monitor runs
136
+ */
137
+ list(monitorId: string, options?: ListSearchMonitorRunsParams): Promise<ListSearchMonitorRunsResponse>;
138
+ /**
139
+ * Get a specific Search Monitor run
140
+ * @param monitorId The ID of the Search Monitor
141
+ * @param runId The ID of the run
142
+ * @returns The Search Monitor run
143
+ */
144
+ get(monitorId: string, runId: string): Promise<SearchMonitorRun>;
145
+ /**
146
+ * Iterate through all runs for a Search Monitor, handling pagination automatically
147
+ * @param monitorId The ID of the Search Monitor
148
+ * @param options Pagination options
149
+ * @returns Async generator of Search Monitor runs
150
+ */
151
+ listAll(monitorId: string, options?: ListSearchMonitorRunsParams): AsyncGenerator<SearchMonitorRun>;
152
+ /**
153
+ * Collect all runs for a Search Monitor into an array
154
+ * @param monitorId The ID of the Search Monitor
155
+ * @param options Pagination options
156
+ * @returns Promise resolving to an array of all Search Monitor runs
157
+ */
158
+ getAll(monitorId: string, options?: ListSearchMonitorRunsParams): Promise<SearchMonitorRun[]>;
159
+ }
160
+ /**
161
+ * Client for managing Search Monitors
162
+ */
163
+ declare class SearchMonitorsClient extends SearchMonitorsBaseClient {
164
+ /**
165
+ * Client for managing Search Monitor Runs
166
+ */
167
+ runs: SearchMonitorRunsClient;
168
+ constructor(client: Exa);
169
+ /**
170
+ * Create a Search Monitor
171
+ * @param params The monitor creation parameters
172
+ * @returns The created Search Monitor with webhookSecret
173
+ */
174
+ create(params: CreateSearchMonitorParams): Promise<CreateSearchMonitorResponse>;
175
+ /**
176
+ * Get a Search Monitor by ID
177
+ * @param id The ID of the Search Monitor
178
+ * @returns The Search Monitor
179
+ */
180
+ get(id: string): Promise<SearchMonitor>;
181
+ /**
182
+ * List Search Monitors
183
+ * @param options Pagination and filtering options
184
+ * @returns The list of Search Monitors
185
+ */
186
+ list(options?: ListSearchMonitorsParams): Promise<ListSearchMonitorsResponse>;
187
+ /**
188
+ * Update a Search Monitor
189
+ * @param id The ID of the Search Monitor
190
+ * @param params The update parameters
191
+ * @returns The updated Search Monitor
192
+ */
193
+ update(id: string, params: UpdateSearchMonitorParams): Promise<SearchMonitor>;
194
+ /**
195
+ * Delete a Search Monitor
196
+ * @param id The ID of the Search Monitor
197
+ * @returns The deleted Search Monitor
198
+ */
199
+ delete(id: string): Promise<SearchMonitor>;
200
+ /**
201
+ * Trigger a Search Monitor run immediately
202
+ * @param id The ID of the Search Monitor
203
+ * @returns Whether the monitor was triggered
204
+ */
205
+ trigger(id: string): Promise<TriggerSearchMonitorResponse>;
206
+ /**
207
+ * Iterate through all Search Monitors, handling pagination automatically
208
+ * @param options Pagination and filtering options
209
+ * @returns Async generator of Search Monitors
210
+ */
211
+ listAll(options?: ListSearchMonitorsParams): AsyncGenerator<SearchMonitor>;
212
+ /**
213
+ * Collect all Search Monitors into an array
214
+ * @param options Pagination and filtering options
215
+ * @returns Promise resolving to an array of all Search Monitors
216
+ */
217
+ getAll(options?: ListSearchMonitorsParams): Promise<SearchMonitor[]>;
218
+ }
219
+
3
220
  interface components$1 {
4
221
  schemas: {
5
222
  ListResearchResponseDto: {
@@ -1742,6 +1959,8 @@ interface components {
1742
1959
  * @description The date and time the webset was created
1743
1960
  */
1744
1961
  createdAt: string;
1962
+ /** @description The URL to view the webset in the Exa dashboard */
1963
+ dashboardUrl: string;
1745
1964
  /** @description The Enrichments to apply to the Webset Items. */
1746
1965
  enrichments: components["schemas"]["WebsetEnrichment"][];
1747
1966
  /** @description The Excludes sources (existing imports or websets) that apply to all operations within this Webset. Any results found within these sources will be omitted across all search and import operations. */
@@ -3094,7 +3313,7 @@ type BaseRegularSearchOptions = BaseSearchOptions & {
3094
3313
  moderation?: boolean;
3095
3314
  useAutoprompt?: boolean;
3096
3315
  };
3097
- type DeepSearchType = "deep" | "deep-reasoning" | "deep-max";
3316
+ type DeepSearchType = "deep" | "deep-reasoning";
3098
3317
  /**
3099
3318
  * Deep search output schema mode for plain text responses.
3100
3319
  */
@@ -3146,6 +3365,11 @@ type DeepSearchOptions = Omit<BaseRegularSearchOptions, "contents"> & {
3146
3365
  * @example ["machine learning", "ML algorithms", "neural networks"]
3147
3366
  */
3148
3367
  additionalQueries?: string[];
3368
+ /**
3369
+ * Additional instructions that guide both deep-search planning and the final returned synthesis.
3370
+ * Use this to prefer certain sources, emphasize novelty, avoid duplicates, or constrain output style.
3371
+ */
3372
+ systemPrompt?: string;
3149
3373
  /**
3150
3374
  * Output schema for deep search responses.
3151
3375
  * - `type: "text"` for plain text output (optionally guided by `description`)
@@ -3578,6 +3802,10 @@ declare class Exa {
3578
3802
  * Research API client
3579
3803
  */
3580
3804
  research: ResearchClient;
3805
+ /**
3806
+ * Search Monitors API client
3807
+ */
3808
+ monitors: SearchMonitorsClient;
3581
3809
  /**
3582
3810
  * Helper method to separate out the contents-specific options from the rest.
3583
3811
  */
@@ -3789,4 +4017,4 @@ declare class Exa {
3789
4017
  private parseSSEStream;
3790
4018
  }
3791
4019
 
3792
- export { type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type 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 SearchResponse, type SearchResult, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, 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 };
4020
+ export { type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type 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
@@ -1,5 +1,222 @@
1
1
  import { ZodSchema } from 'zod';
2
2
 
3
+ /**
4
+ * Types for the Search Monitors API
5
+ */
6
+
7
+ type SearchMonitorStatus = "active" | "paused" | "disabled";
8
+ type SearchMonitorRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
9
+ type SearchMonitorRunFailReason = "api_key_invalid" | "insufficient_credits" | "invalid_params" | "rate_limited" | "search_unavailable" | "search_failed" | "internal_error";
10
+ type SearchMonitorWebhookEvent = "monitor.created" | "monitor.updated" | "monitor.deleted" | "monitor.run.created" | "monitor.run.completed";
11
+ interface SearchMonitorSearch {
12
+ query: string;
13
+ numResults?: number;
14
+ includeDomains?: string[];
15
+ excludeDomains?: string[];
16
+ contents?: ContentsOptions;
17
+ }
18
+ interface SearchMonitorTrigger {
19
+ type: "cron";
20
+ expression: string;
21
+ timezone?: string;
22
+ }
23
+ interface SearchMonitorWebhook {
24
+ url: string;
25
+ events?: SearchMonitorWebhookEvent[];
26
+ }
27
+ interface GroundingCitation {
28
+ url: string;
29
+ title: string;
30
+ }
31
+ interface GroundingEntry {
32
+ field: string;
33
+ citations: GroundingCitation[];
34
+ confidence: "low" | "medium" | "high";
35
+ }
36
+ interface SearchMonitorRunOutput {
37
+ results?: Record<string, unknown>[] | null;
38
+ content?: string | null;
39
+ grounding?: GroundingEntry[] | null;
40
+ }
41
+ interface SearchMonitor {
42
+ id: string;
43
+ name: string | null;
44
+ status: SearchMonitorStatus;
45
+ search: SearchMonitorSearch;
46
+ trigger: SearchMonitorTrigger | null;
47
+ outputSchema: Record<string, unknown> | null;
48
+ metadata: Record<string, string> | null;
49
+ webhook: SearchMonitorWebhook;
50
+ nextRunAt: string | null;
51
+ createdAt: string;
52
+ updatedAt: string;
53
+ }
54
+ interface CreateSearchMonitorResponse extends SearchMonitor {
55
+ webhookSecret: string;
56
+ }
57
+ interface SearchMonitorRun {
58
+ id: string;
59
+ monitorId: string;
60
+ status: SearchMonitorRunStatus;
61
+ output: SearchMonitorRunOutput | null;
62
+ failReason: SearchMonitorRunFailReason | null;
63
+ startedAt: string | null;
64
+ completedAt: string | null;
65
+ failedAt: string | null;
66
+ cancelledAt: string | null;
67
+ durationMs: number | null;
68
+ createdAt: string;
69
+ updatedAt: string;
70
+ }
71
+ interface CreateSearchMonitorParams {
72
+ name?: string;
73
+ search: SearchMonitorSearch;
74
+ trigger?: SearchMonitorTrigger;
75
+ outputSchema?: Record<string, unknown>;
76
+ metadata?: Record<string, string>;
77
+ webhook: SearchMonitorWebhook;
78
+ }
79
+ interface UpdateSearchMonitorParams {
80
+ name?: string | null;
81
+ status?: SearchMonitorStatus;
82
+ search?: SearchMonitorSearch;
83
+ trigger?: SearchMonitorTrigger | null;
84
+ outputSchema?: Record<string, unknown> | null;
85
+ metadata?: Record<string, string> | null;
86
+ webhook?: SearchMonitorWebhook;
87
+ }
88
+ interface ListSearchMonitorsParams {
89
+ cursor?: string;
90
+ limit?: number;
91
+ status?: SearchMonitorStatus;
92
+ }
93
+ interface ListSearchMonitorRunsParams {
94
+ cursor?: string;
95
+ limit?: number;
96
+ }
97
+ interface ListSearchMonitorsResponse {
98
+ data: SearchMonitor[];
99
+ hasMore: boolean;
100
+ nextCursor: string | null;
101
+ }
102
+ interface ListSearchMonitorRunsResponse {
103
+ data: SearchMonitorRun[];
104
+ hasMore: boolean;
105
+ nextCursor: string | null;
106
+ }
107
+ interface TriggerSearchMonitorResponse {
108
+ triggered: boolean;
109
+ }
110
+
111
+ /**
112
+ * Base client for Search Monitors API
113
+ */
114
+
115
+ type QueryParams$2 = Record<string, string | number | boolean | string[] | undefined>;
116
+ declare class SearchMonitorsBaseClient {
117
+ protected client: Exa;
118
+ constructor(client: Exa);
119
+ protected request<T = unknown>(endpoint: string, method?: string, data?: Record<string, any>, params?: QueryParams$2): Promise<T>;
120
+ protected buildPaginationParams(pagination?: ListSearchMonitorsParams | ListSearchMonitorRunsParams): QueryParams$2;
121
+ }
122
+
123
+ /**
124
+ * Client for the Search Monitors API
125
+ */
126
+
127
+ /**
128
+ * Client for managing Search Monitor Runs
129
+ */
130
+ declare class SearchMonitorRunsClient extends SearchMonitorsBaseClient {
131
+ /**
132
+ * List all runs for a Search Monitor
133
+ * @param monitorId The ID of the Search Monitor
134
+ * @param options Pagination options
135
+ * @returns The list of Search Monitor runs
136
+ */
137
+ list(monitorId: string, options?: ListSearchMonitorRunsParams): Promise<ListSearchMonitorRunsResponse>;
138
+ /**
139
+ * Get a specific Search Monitor run
140
+ * @param monitorId The ID of the Search Monitor
141
+ * @param runId The ID of the run
142
+ * @returns The Search Monitor run
143
+ */
144
+ get(monitorId: string, runId: string): Promise<SearchMonitorRun>;
145
+ /**
146
+ * Iterate through all runs for a Search Monitor, handling pagination automatically
147
+ * @param monitorId The ID of the Search Monitor
148
+ * @param options Pagination options
149
+ * @returns Async generator of Search Monitor runs
150
+ */
151
+ listAll(monitorId: string, options?: ListSearchMonitorRunsParams): AsyncGenerator<SearchMonitorRun>;
152
+ /**
153
+ * Collect all runs for a Search Monitor into an array
154
+ * @param monitorId The ID of the Search Monitor
155
+ * @param options Pagination options
156
+ * @returns Promise resolving to an array of all Search Monitor runs
157
+ */
158
+ getAll(monitorId: string, options?: ListSearchMonitorRunsParams): Promise<SearchMonitorRun[]>;
159
+ }
160
+ /**
161
+ * Client for managing Search Monitors
162
+ */
163
+ declare class SearchMonitorsClient extends SearchMonitorsBaseClient {
164
+ /**
165
+ * Client for managing Search Monitor Runs
166
+ */
167
+ runs: SearchMonitorRunsClient;
168
+ constructor(client: Exa);
169
+ /**
170
+ * Create a Search Monitor
171
+ * @param params The monitor creation parameters
172
+ * @returns The created Search Monitor with webhookSecret
173
+ */
174
+ create(params: CreateSearchMonitorParams): Promise<CreateSearchMonitorResponse>;
175
+ /**
176
+ * Get a Search Monitor by ID
177
+ * @param id The ID of the Search Monitor
178
+ * @returns The Search Monitor
179
+ */
180
+ get(id: string): Promise<SearchMonitor>;
181
+ /**
182
+ * List Search Monitors
183
+ * @param options Pagination and filtering options
184
+ * @returns The list of Search Monitors
185
+ */
186
+ list(options?: ListSearchMonitorsParams): Promise<ListSearchMonitorsResponse>;
187
+ /**
188
+ * Update a Search Monitor
189
+ * @param id The ID of the Search Monitor
190
+ * @param params The update parameters
191
+ * @returns The updated Search Monitor
192
+ */
193
+ update(id: string, params: UpdateSearchMonitorParams): Promise<SearchMonitor>;
194
+ /**
195
+ * Delete a Search Monitor
196
+ * @param id The ID of the Search Monitor
197
+ * @returns The deleted Search Monitor
198
+ */
199
+ delete(id: string): Promise<SearchMonitor>;
200
+ /**
201
+ * Trigger a Search Monitor run immediately
202
+ * @param id The ID of the Search Monitor
203
+ * @returns Whether the monitor was triggered
204
+ */
205
+ trigger(id: string): Promise<TriggerSearchMonitorResponse>;
206
+ /**
207
+ * Iterate through all Search Monitors, handling pagination automatically
208
+ * @param options Pagination and filtering options
209
+ * @returns Async generator of Search Monitors
210
+ */
211
+ listAll(options?: ListSearchMonitorsParams): AsyncGenerator<SearchMonitor>;
212
+ /**
213
+ * Collect all Search Monitors into an array
214
+ * @param options Pagination and filtering options
215
+ * @returns Promise resolving to an array of all Search Monitors
216
+ */
217
+ getAll(options?: ListSearchMonitorsParams): Promise<SearchMonitor[]>;
218
+ }
219
+
3
220
  interface components$1 {
4
221
  schemas: {
5
222
  ListResearchResponseDto: {
@@ -1742,6 +1959,8 @@ interface components {
1742
1959
  * @description The date and time the webset was created
1743
1960
  */
1744
1961
  createdAt: string;
1962
+ /** @description The URL to view the webset in the Exa dashboard */
1963
+ dashboardUrl: string;
1745
1964
  /** @description The Enrichments to apply to the Webset Items. */
1746
1965
  enrichments: components["schemas"]["WebsetEnrichment"][];
1747
1966
  /** @description The Excludes sources (existing imports or websets) that apply to all operations within this Webset. Any results found within these sources will be omitted across all search and import operations. */
@@ -3094,7 +3313,7 @@ type BaseRegularSearchOptions = BaseSearchOptions & {
3094
3313
  moderation?: boolean;
3095
3314
  useAutoprompt?: boolean;
3096
3315
  };
3097
- type DeepSearchType = "deep" | "deep-reasoning" | "deep-max";
3316
+ type DeepSearchType = "deep" | "deep-reasoning";
3098
3317
  /**
3099
3318
  * Deep search output schema mode for plain text responses.
3100
3319
  */
@@ -3146,6 +3365,11 @@ type DeepSearchOptions = Omit<BaseRegularSearchOptions, "contents"> & {
3146
3365
  * @example ["machine learning", "ML algorithms", "neural networks"]
3147
3366
  */
3148
3367
  additionalQueries?: string[];
3368
+ /**
3369
+ * Additional instructions that guide both deep-search planning and the final returned synthesis.
3370
+ * Use this to prefer certain sources, emphasize novelty, avoid duplicates, or constrain output style.
3371
+ */
3372
+ systemPrompt?: string;
3149
3373
  /**
3150
3374
  * Output schema for deep search responses.
3151
3375
  * - `type: "text"` for plain text output (optionally guided by `description`)
@@ -3578,6 +3802,10 @@ declare class Exa {
3578
3802
  * Research API client
3579
3803
  */
3580
3804
  research: ResearchClient;
3805
+ /**
3806
+ * Search Monitors API client
3807
+ */
3808
+ monitors: SearchMonitorsClient;
3581
3809
  /**
3582
3810
  * Helper method to separate out the contents-specific options from the rest.
3583
3811
  */
@@ -3789,4 +4017,4 @@ declare class Exa {
3789
4017
  private parseSSEStream;
3790
4018
  }
3791
4019
 
3792
- export { type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type 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 SearchResponse, type SearchResult, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, 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 };
4020
+ export { type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type 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 };