parallel-web 0.1.1 → 0.2.0

package/src/resources/beta/beta.ts

@@ -30,20 +30,128 @@ import {
   Webhook,
 } from './task-run';
 import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 
 export class Beta extends APIResource {
   taskRun: TaskRunAPI.TaskRun = new TaskRunAPI.TaskRun(this._client);
   taskGroup: TaskGroupAPI.TaskGroup = new TaskGroupAPI.TaskGroup(this._client);
 
+  /**
+   * Extracts relevant content from specific web URLs.
+   *
+   * To access this endpoint, pass the `parallel-beta` header with the value
+   * `search-extract-2025-10-10`.
+   */
+  extract(params: BetaExtractParams, options?: RequestOptions): APIPromise<ExtractResponse> {
+    const { betas, ...body } = params;
+    return this._client.post('/v1beta/extract', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(betas?.toString() != null ? { 'parallel-beta': betas?.toString() } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Searches the web.
    */
-  search(body: BetaSearchParams, options?: RequestOptions): APIPromise<SearchResult> {
-    return this._client.post('/v1beta/search', { body, ...options });
+  search(params: BetaSearchParams, options?: RequestOptions): APIPromise<SearchResult> {
+    const { betas, ...body } = params;
+    return this._client.post('/v1beta/search', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(betas?.toString() != null ? { 'parallel-beta': betas?.toString() } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 }
 
+/**
+ * Optional settings for returning relevant excerpts.
+ */
+export interface ExcerptSettings {
+  /**
+   * Optional upper bound on the total number of characters to include across all
+   * excerpts for each url. Excerpts may contain fewer characters than this limit to
+   * maximize relevance and token efficiency.
+   */
+  max_chars_per_result?: number | null;
+}
+
+/**
+ * Extract error details.
+ */
+export interface ExtractError {
+  /**
+   * Content returned for http client or server errors, if any.
+   */
+  content: string | null;
+
+  /**
+   * Error type.
+   */
+  error_type: string;
+
+  /**
+   * HTTP status code, if available.
+   */
+  http_status_code: number | null;
+
+  url: string;
+}
+
+/**
+ * Fetch result.
+ */
+export interface ExtractResponse {
+  /**
+   * Extract errors: requested URLs not in the results.
+   */
+  errors: Array<ExtractError>;
+
+  /**
+   * Extract request ID, e.g. `extract_cad0a6d2dec046bd95ae900527d880e7`
+   */
+  extract_id: string;
+
+  /**
+   * Successful extract results.
+   */
+  results: Array<ExtractResult>;
+}
+
+/**
+ * Extract result for a single URL.
+ */
+export interface ExtractResult {
+  /**
+   * Relevant excerpted content from the URL, formatted as markdown.
+   */
+  excerpts: Array<string> | null;
+
+  /**
+   * Full content from the URL formatted as markdown, if requested.
+   */
+  full_content: string | null;
+
+  /**
+   * Publish date of the webpage, if available.
+   */
+  publish_date: string | null;
+
+  /**
+   * Title of the webpage, if available.
+   */
+  title: string | null;
+
+  url: string;
+}
+
 /**
  * Output for the Search API.
  */
@@ -54,7 +162,7 @@ export interface SearchResult {
   results: Array<WebSearchResult>;
 
   /**
-   * Search ID. Example: `search_cad0a6d2-dec0-46bd-95ae-900527d880e7`
+   * Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`
    */
   search_id: string;
 }
@@ -79,52 +187,150 @@ export interface WebSearchResult {
   url: string;
 }
 
+export interface BetaExtractParams {
+  /**
+   * Body param:
+   */
+  urls: Array<string>;
+
+  /**
+   * Body param: Include excerpts from each URL relevant to the search objective and
+   * queries. Note that if neither objective nor search_queries is provided, excerpts
+   * are redundant with full content.
+   */
+  excerpts?: boolean | ExcerptSettings;
+
+  /**
+   * Body param: Fetch policy.
+   *
+   * Determines when to return content from the cache (faster) vs fetching live
+   * content (fresher).
+   */
+  fetch_policy?: BetaExtractParams.FetchPolicy | null;
+
+  /**
+   * Body param: Include full content from each URL. Note that if neither objective
+   * nor search_queries is provided, excerpts are redundant with full content.
+   */
+  full_content?: boolean | BetaExtractParams.FullContentSettings;
+
+  /**
+   * Body param: If provided, focuses extracted content on the specified search
+   * objective.
+   */
+  objective?: string | null;
+
+  /**
+   * Body param: If provided, focuses extracted content on the specified keyword
+   * search queries.
+   */
+  search_queries?: Array<string> | null;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) to enable.
+   */
+  betas?: Array<TaskRunAPI.ParallelBeta>;
+}
+
+export namespace BetaExtractParams {
+  /**
+   * Fetch policy.
+   *
+   * Determines when to return content from the cache (faster) vs fetching live
+   * content (fresher).
+   */
+  export interface FetchPolicy {
+    /**
+     * If false, fallback to cached content older than max-age if live fetch fails or
+     * times out. If true, returns an error instead.
+     */
+    disable_cache_fallback?: boolean;
+
+    /**
+     * Maximum age of cached content in seconds to trigger a live fetch. Minimum value
+     * 600 seconds (10 minutes). If not provided, a dynamic age policy will be used
+     * based on the search objective and url.
+     */
+    max_age_seconds?: number | null;
+
+    /**
+     * Timeout in seconds for fetching live content if unavailable in cache. If
+     * unspecified a dynamic timeout will be used based on the url, generally 15
+     * seconds for simple pages and up to 60 seconds for complex pages requiring
+     * javascript or PDF rendering.
+     */
+    timeout_seconds?: number | null;
+  }
+
+  /**
+   * Optional settings for returning full content.
+   */
+  export interface FullContentSettings {
+    /**
+     * Optional limit on the number of characters to include in the full content for
+     * each url. Full content always starts at the beginning of the page and is
+     * truncated at the limit if necessary.
+     */
+    max_chars_per_result?: number | null;
+  }
+}
+
 export interface BetaSearchParams {
   /**
-   * Upper bound on the number of characters to include in excerpts for each search
-   * result.
+   * Body param: Upper bound on the number of characters to include in excerpts for
+   * each search result.
    */
   max_chars_per_result?: number | null;
 
   /**
-   * Upper bound on the number of results to return. May be limited by the processor.
-   * Defaults to 10 if not provided.
+   * Body param: Upper bound on the number of results to return. May be limited by
+   * the processor. Defaults to 10 if not provided.
    */
   max_results?: number | null;
 
   /**
-   * Natural-language description of what the web search is trying to find. May
-   * include guidance about preferred sources or freshness. At least one of objective
-   * or search_queries must be provided.
+   * Body param: Natural-language description of what the web search is trying to
+   * find. May include guidance about preferred sources or freshness. At least one of
+   * objective or search_queries must be provided.
    */
   objective?: string | null;
 
   /**
-   * Search processor.
+   * Body param: Search processor.
    */
-  processor?: 'base' | 'pro';
+  processor?: 'base' | 'pro' | null;
 
   /**
-   * Optional list of traditional keyword search queries to guide the search. May
-   * contain search operators. At least one of objective or search_queries must be
-   * provided.
+   * Body param: Optional list of traditional keyword search queries to guide the
+   * search. May contain search operators. At least one of objective or
+   * search_queries must be provided.
    */
   search_queries?: Array<string> | null;
 
   /**
-   * Source policy for web search results.
+   * Body param: Source policy for web search results.
    *
    * This policy governs which sources are allowed/disallowed in results.
    */
   source_policy?: Shared.SourcePolicy | null;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) to enable.
+   */
+  betas?: Array<TaskRunAPI.ParallelBeta>;
 }
 
 Beta.TaskRun = TaskRun;
 
 export declare namespace Beta {
   export {
+    type ExcerptSettings as ExcerptSettings,
+    type ExtractError as ExtractError,
+    type ExtractResponse as ExtractResponse,
+    type ExtractResult as ExtractResult,
     type SearchResult as SearchResult,
     type WebSearchResult as WebSearchResult,
+    type BetaExtractParams as BetaExtractParams,
     type BetaSearchParams as BetaSearchParams,
   };
 

package/src/resources/beta/task-group.ts

@@ -47,8 +47,8 @@ export class TaskGroup extends APIResource {
   /**
    * Streams events from a TaskGroup: status updates and run completions.
    *
-   * The connection will remain open for up to 10 minutes as long as at least one run
-   * in the TaskGroup is active.
+   * The connection will remain open for up to an hour as long as at least one run in
+   * the group is still active.
    */
   events(
     taskGroupID: string,
@@ -65,6 +65,15 @@ export class TaskGroup extends APIResource {
 
   /**
    * Retrieves task runs in a TaskGroup and optionally their inputs and outputs.
+   *
+   * All runs within a TaskGroup are returned as a stream. To get the inputs and/or
+   * outputs back in the stream, set the corresponding `include_input` and
+   * `include_output` parameters to `true`.
+   *
+   * The stream is resumable using the `event_id` as the cursor. To resume a stream,
+   * specify the `last_event_id` parameter with the `event_id` of the last event in
+   * the stream. The stream will resume from the next event after the
+   * `last_event_id`.
    */
   getRuns(
     taskGroupID: string,

package/src/resources/beta/task-run.ts

@@ -87,16 +87,16 @@ export interface BetaRunInput {
    * [Task Run events](https://platform.parallel.ai/api-reference) endpoint. When
    * false, no progress events are tracked. Note that progress tracking cannot be
    * enabled after a run has been created. The flag is set to true by default for
-   * premium processors (pro and above). This feature is not available via the Python
-   * SDK. To enable this feature in your API requests, specify the `parallel-beta`
-   * header with `events-sse-2025-07-24` value.
+   * premium processors (pro and above). To enable this feature in your requests,
+   * specify `events-sse-2025-07-24` as one of the values in `parallel-beta` header
+   * (for API calls) or `betas` param (for the SDKs).
    */
   enable_events?: boolean | null;
 
   /**
-   * Optional list of MCP servers to use for the run. This feature is not available
-   * via the Python SDK. To enable this feature in your API requests, specify the
-   * `parallel-beta` header with `mcp-server-2025-07-17` value.
+   * Optional list of MCP servers to use for the run. To enable this feature in your
+   * requests, specify `mcp-server-2025-07-17` as one of the values in
+   * `parallel-beta` header (for API calls) or `betas` param (for the SDKs).
    */
   mcp_servers?: Array<McpServer> | null;
 
@@ -365,6 +365,12 @@ export namespace TaskRunEventsResponse {
    * A progress update for a task run.
    */
   export interface TaskRunProgressStatsEvent {
+    /**
+     * Completion percentage of the task run. Ranges from 0 to 100 where 0 indicates no
+     * progress and 100 indicates completion.
+     */
+    progress_meter: number;
+
     /**
      * Source stats for a task run.
      */
@@ -441,16 +447,16 @@ export interface TaskRunCreateParams {
    * [Task Run events](https://platform.parallel.ai/api-reference) endpoint. When
    * false, no progress events are tracked. Note that progress tracking cannot be
    * enabled after a run has been created. The flag is set to true by default for
-   * premium processors (pro and above). This feature is not available via the Python
-   * SDK. To enable this feature in your API requests, specify the `parallel-beta`
-   * header with `events-sse-2025-07-24` value.
+   * premium processors (pro and above). To enable this feature in your requests,
+   * specify `events-sse-2025-07-24` as one of the values in `parallel-beta` header
+   * (for API calls) or `betas` param (for the SDKs).
    */
   enable_events?: boolean | null;
 
   /**
-   * Body param: Optional list of MCP servers to use for the run. This feature is not
-   * available via the Python SDK. To enable this feature in your API requests,
-   * specify the `parallel-beta` header with `mcp-server-2025-07-17` value.
+   * Body param: Optional list of MCP servers to use for the run. To enable this
+   * feature in your requests, specify `mcp-server-2025-07-17` as one of the values
+   * in `parallel-beta` header (for API calls) or `betas` param (for the SDKs).
    */
   mcp_servers?: Array<McpServer> | null;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.1.1'; // x-release-please-version
+export const VERSION = '0.2.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.2.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.2.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.1.1'; // x-release-please-version
+exports.VERSION = '0.2.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.1.1'; // x-release-please-version
+export const VERSION = '0.2.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map