exa-js 1.7.2 → 1.7.3

package/README.md

@@ -190,7 +190,7 @@ Each chunk contains:
 - `content`: A string containing the next piece of generated text
 - `citations`: An array of citation objects containing source information
 
-### `exa.research.createTask(input: object, options?: { schema?: object }): Promise<ResearchTaskResponse>`
+### `exa.research.createTask(input: object, options?: { schema?: object }): Promise<{id: string}>`
 
 Exa's research agent can autonomously gather information and return a structured JSON object that conforms to a schema you provide.
 
@@ -207,12 +207,13 @@ const schema = {
   },
 };
 
-const response = await exa.research.createTask(
+const { id: taskId } = await exa.research.createTask(
   {
     instructions: "In ≤3 sentences, explain quantum computing.",
   },
   { schema }
 );
+const result = await exa.research.pollTask(taskId);
 ```
 
 Use the `status` field to poll long-running tasks if needed (a future `getTask` helper will be added when the async API is released).

package/dist/index.d.mts

@@ -1340,33 +1340,6 @@ declare class WebsetsClient extends WebsetsBaseClient {
     } | number): Promise<Webset>;
 }
 
-/**
- * Enum representing the status of a research task.
- */
-declare enum ResearchStatus {
-    /** The research request has finished successfully. */
-    completed = "completed",
-    /** The research request failed. */
-    failed = "failed"
-}
-/**
- * Response object returned from the research API.
- */
-type ResearchTaskResponse = {
-    /** Unique identifier for the task. */
-    id: string;
-    /** Current status (may include future enum values served by the API). */
-    status: ResearchStatus | string;
-    /** Structured output that follows the user-provided schema (null while running). */
-    output: Record<string, any> | null;
-    /**
-     * Citations collected while deriving each top-level field in `output`.
-     * The key is the field name, the value is the list of `SearchResult`s that
-     * were used to compute that field.
-     */
-    citations: Record<string, SearchResult<{}>[]>;
-};
-
 type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
 interface RequestBody {
     [key: string]: unknown;
@@ -1398,7 +1371,7 @@ declare class ResearchBaseClient {
 declare class ResearchClient extends ResearchBaseClient {
     constructor(client: Exa);
     /**
-     * Create and run a research task (blocking call).
+     * Create a research task.
      *
      * Both parameters are required and have fixed shapes:
      * 1. `input`
@@ -1417,15 +1390,52 @@ declare class ResearchClient extends ResearchBaseClient {
         instructions: string;
     }, output: {
         schema: JSONSchema;
-    }): Promise<ResearchTaskResponse>;
+    }): Promise<{
+        id: string;
+    }>;
     /**
      * Retrieve a research task by ID.
-     *
-     * Not yet implemented server-side. Calling this will throw until the API is
-     * available.
      */
-    getTask(): Promise<ResearchTaskResponse>;
+    getTask(id: string): Promise<ResearchTask>;
+    /**
+     * Poll a research task until completion or failure.
+     * Polls every 1 second with a maximum timeout of 10 minutes.
+     */
+    pollTask(id: string): Promise<ResearchTask>;
+}
+
+/**
+ * Enum representing the status of a research task.
+ */
+declare enum ResearchStatus {
+    /** The research task is still in progress. */
+    in_progress = "in_progress",
+    /** The research request has finished successfully. */
+    completed = "completed",
+    /** The research task request failed. */
+    failed = "failed"
 }
+/**
+ * Response object returned from the research API.
+ */
+type ResearchTask = {
+    /** Unique identifier for the task. */
+    id: string;
+    /** Current status. */
+    status: ResearchStatus;
+    /** The original instructions provided along with the task. */
+    instructions: string;
+    /** The original schema defining the task */
+    schema: Record<string, any>;
+    /** Structured output that follows the user-provided schema (null while running or if failed). */
+    data: Record<string, any> | null;
+    /**
+     * Citations collected while deriving each top-level field in `output`.
+     * The key is the field name, the value is the list of `SearchResult`s that
+     * were used to compute that field.
+     */
+    citations: Record<string, SearchResult<{}>[]>;
+};
 
 /**
  * HTTP status codes
@@ -1904,4 +1914,4 @@ declare class Exa {
     private parseSSEStream;
 }
 
-export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTaskResponse, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };
+export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTask, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };

package/dist/index.d.ts

@@ -1340,33 +1340,6 @@ declare class WebsetsClient extends WebsetsBaseClient {
     } | number): Promise<Webset>;
 }
 
-/**
- * Enum representing the status of a research task.
- */
-declare enum ResearchStatus {
-    /** The research request has finished successfully. */
-    completed = "completed",
-    /** The research request failed. */
-    failed = "failed"
-}
-/**
- * Response object returned from the research API.
- */
-type ResearchTaskResponse = {
-    /** Unique identifier for the task. */
-    id: string;
-    /** Current status (may include future enum values served by the API). */
-    status: ResearchStatus | string;
-    /** Structured output that follows the user-provided schema (null while running). */
-    output: Record<string, any> | null;
-    /**
-     * Citations collected while deriving each top-level field in `output`.
-     * The key is the field name, the value is the list of `SearchResult`s that
-     * were used to compute that field.
-     */
-    citations: Record<string, SearchResult<{}>[]>;
-};
-
 type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
 interface RequestBody {
     [key: string]: unknown;
@@ -1398,7 +1371,7 @@ declare class ResearchBaseClient {
 declare class ResearchClient extends ResearchBaseClient {
     constructor(client: Exa);
     /**
-     * Create and run a research task (blocking call).
+     * Create a research task.
      *
      * Both parameters are required and have fixed shapes:
      * 1. `input`
@@ -1417,15 +1390,52 @@ declare class ResearchClient extends ResearchBaseClient {
         instructions: string;
     }, output: {
         schema: JSONSchema;
-    }): Promise<ResearchTaskResponse>;
+    }): Promise<{
+        id: string;
+    }>;
     /**
      * Retrieve a research task by ID.
-     *
-     * Not yet implemented server-side. Calling this will throw until the API is
-     * available.
      */
-    getTask(): Promise<ResearchTaskResponse>;
+    getTask(id: string): Promise<ResearchTask>;
+    /**
+     * Poll a research task until completion or failure.
+     * Polls every 1 second with a maximum timeout of 10 minutes.
+     */
+    pollTask(id: string): Promise<ResearchTask>;
+}
+
+/**
+ * Enum representing the status of a research task.
+ */
+declare enum ResearchStatus {
+    /** The research task is still in progress. */
+    in_progress = "in_progress",
+    /** The research request has finished successfully. */
+    completed = "completed",
+    /** The research task request failed. */
+    failed = "failed"
 }
+/**
+ * Response object returned from the research API.
+ */
+type ResearchTask = {
+    /** Unique identifier for the task. */
+    id: string;
+    /** Current status. */
+    status: ResearchStatus;
+    /** The original instructions provided along with the task. */
+    instructions: string;
+    /** The original schema defining the task */
+    schema: Record<string, any>;
+    /** Structured output that follows the user-provided schema (null while running or if failed). */
+    data: Record<string, any> | null;
+    /**
+     * Citations collected while deriving each top-level field in `output`.
+     * The key is the field name, the value is the list of `SearchResult`s that
+     * were used to compute that field.
+     */
+    citations: Record<string, SearchResult<{}>[]>;
+};
 
 /**
  * HTTP status codes
@@ -1904,4 +1914,4 @@ declare class Exa {
     private parseSSEStream;
 }
 
-export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTaskResponse, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };
+export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTask, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };

package/dist/index.js

@@ -719,7 +719,7 @@ var ResearchClient = class extends ResearchBaseClient {
     super(client);
   }
   /**
-   * Create and run a research task (blocking call).
+   * Create a research task.
    *
    * Both parameters are required and have fixed shapes:
    * 1. `input`
@@ -742,17 +742,36 @@ var ResearchClient = class extends ResearchBaseClient {
   }
   /**
    * Retrieve a research task by ID.
-   *
-   * Not yet implemented server-side. Calling this will throw until the API is
-   * available.
    */
-  async getTask() {
-    throw new Error("getTask is not implemented yet.");
+  async getTask(id) {
+    return this.request(`/tasks/${id}`, "GET");
+  }
+  /**
+   * Poll a research task until completion or failure.
+   * Polls every 1 second with a maximum timeout of 10 minutes.
+   */
+  async pollTask(id) {
+    const pollingInterval = 1e3;
+    const maxPollingTime = 10 * 60 * 1e3;
+    const startTime = Date.now();
+    while (true) {
+      const task = await this.request(`/tasks/${id}`, "GET");
+      if (task.status === "completed" || task.status === "failed") {
+        return task;
+      }
+      if (Date.now() - startTime > maxPollingTime) {
+        throw new Error(
+          `Polling timeout: Task ${id} did not complete within 10 minutes`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollingInterval));
+    }
   }
 };
 
 // src/research/types.ts
 var ResearchStatus = /* @__PURE__ */ ((ResearchStatus2) => {
+  ResearchStatus2["in_progress"] = "in_progress";
   ResearchStatus2["completed"] = "completed";
   ResearchStatus2["failed"] = "failed";
   return ResearchStatus2;