parallel-web 0.4.1 → 0.5.0

package/src/resources/task-group.ts

@@ -0,0 +1,315 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as TaskRunAPI from './task-run';
+import * as BetaTaskRunAPI from './beta/task-run';
+import { APIPromise } from '../core/api-promise';
+import { Stream } from '../core/streaming';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * The Task API executes web research and extraction tasks. Clients submit a natural-language objective with an optional input schema; the service plans retrieval, fetches relevant URLs, and returns outputs that conform to a provided or inferred JSON schema. Supports deep research style queries and can return rich structured JSON outputs. Processors trade-off between cost, latency, and quality. Each processor supports calibrated confidences.
+ * - Output metadata: citations, excerpts, reasoning, and confidence per field
+ *
+ * Task Groups enable batch execution of many independent Task runs with group-level monitoring and failure handling.
+ * - Submit hundreds or thousands of Tasks as a single group
+ * - Observe group progress and receive results as they complete
+ * - Real-time updates via Server-Sent Events (SSE)
+ * - Add tasks to an existing group while it is running
+ * - Group-level retry and error aggregation
+ */
+export class TaskGroup extends APIResource {
+  /**
+   * Initiates a TaskGroup to group and track multiple runs.
+   */
+  create(body: TaskGroupCreateParams, options?: RequestOptions): APIPromise<TaskGroup> {
+    return this._client.post('/v1/tasks/groups', { body, ...options });
+  }
+
+  /**
+   * Retrieves aggregated status across runs in a TaskGroup.
+   */
+  retrieve(taskGroupID: string, options?: RequestOptions): APIPromise<TaskGroup> {
+    return this._client.get(path`/v1/tasks/groups/${taskGroupID}`, options);
+  }
+
+  /**
+   * Initiates multiple task runs within a TaskGroup.
+   */
+  addRuns(
+    taskGroupID: string,
+    params: TaskGroupAddRunsParams,
+    options?: RequestOptions,
+  ): APIPromise<TaskGroupRunResponse> {
+    const { refresh_status, betas, ...body } = params;
+    return this._client.post(path`/v1/tasks/groups/${taskGroupID}/runs`, {
+      query: { refresh_status },
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(betas?.toString() != null ? { 'parallel-beta': betas?.toString() } : undefined) },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Streams events from a TaskGroup: status updates and run completions.
+   *
+   * 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,
+    query: TaskGroupEventsParams | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Stream<TaskGroupEventsResponse>> {
+    return this._client.get(path`/v1/tasks/groups/${taskGroupID}/events`, {
+      query,
+      ...options,
+      headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
+      stream: true,
+    }) as APIPromise<Stream<TaskGroupEventsResponse>>;
+  }
+
+  /**
+   * 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,
+    query: TaskGroupGetRunsParams | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Stream<TaskGroupGetRunsResponse>> {
+    return this._client.get(path`/v1/tasks/groups/${taskGroupID}/runs`, {
+      query,
+      ...options,
+      headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
+      stream: true,
+    }) as APIPromise<Stream<TaskGroupGetRunsResponse>>;
+  }
+
+  /**
+   * Retrieves run status by run_id.
+   *
+   * This endpoint is equivalent to fetching run status directly using the
+   * `retrieve()` method or the `tasks/runs` GET endpoint.
+   *
+   * The run result is available from the `/result` endpoint.
+   */
+  retrieveRun(
+    runID: string,
+    params: TaskGroupRetrieveRunParams,
+    options?: RequestOptions,
+  ): APIPromise<TaskRunAPI.TaskRun> {
+    const { taskgroup_id } = params;
+    return this._client.get(path`/v1/tasks/groups/${taskgroup_id}/runs/${runID}`, options);
+  }
+}
+
+/**
+ * Response object for a task group, including its status and metadata.
+ */
+export interface TaskGroup {
+  /**
+   * Timestamp of the creation of the group, as an RFC 3339 string.
+   */
+  created_at: string | null;
+
+  /**
+   * Status of the group.
+   */
+  status: TaskGroupStatus;
+
+  /**
+   * ID of the group.
+   */
+  taskgroup_id: string;
+
+  /**
+   * User-provided metadata stored with the group.
+   */
+  metadata?: { [key: string]: string | number | boolean } | null;
+}
+
+/**
+ * Response from adding new task runs to a task group.
+ */
+export interface TaskGroupRunResponse {
+  /**
+   * Cursor for these runs in the event stream at
+   * taskgroup/events?last_event_id=<event_cursor>. Empty for the first runs in the
+   * group.
+   */
+  event_cursor: string | null;
+
+  /**
+   * Cursor for these runs in the run stream at
+   * taskgroup/runs?last_event_id=<run_cursor>. Empty for the first runs in the
+   * group.
+   */
+  run_cursor: string | null;
+
+  /**
+   * IDs of the newly created runs.
+   */
+  run_ids: Array<string>;
+
+  /**
+   * Status of the group.
+   */
+  status: TaskGroupStatus;
+}
+
+/**
+ * Status of a task group.
+ */
+export interface TaskGroupStatus {
+  /**
+   * True if at least one run in the group is currently active, i.e. status is one of
+   * {'cancelling', 'queued', 'running'}.
+   */
+  is_active: boolean;
+
+  /**
+   * Timestamp of the last status update to the group, as an RFC 3339 string.
+   */
+  modified_at: string | null;
+
+  /**
+   * Number of task runs in the group.
+   */
+  num_task_runs: number;
+
+  /**
+   * Human-readable status message for the group.
+   */
+  status_message: string | null;
+
+  /**
+   * Number of task runs with each status.
+   */
+  task_run_status_counts: { [key: string]: number };
+}
+
+/**
+ * Event indicating an update to group status.
+ */
+export interface TaskGroupStatusEvent {
+  /**
+   * Cursor to resume the event stream.
+   */
+  event_id: string;
+
+  /**
+   * Task group status object.
+   */
+  status: TaskGroupStatus;
+
+  /**
+   * Event type; always 'task_group_status'.
+   */
+  type: 'task_group_status';
+}
+
+/**
+ * Event indicating an update to group status.
+ */
+export type TaskGroupEventsResponse = TaskGroupStatusEvent | TaskRunAPI.TaskRunEvent | TaskRunAPI.ErrorEvent;
+
+/**
+ * Event when a task run transitions to a non-active status.
+ *
+ * May indicate completion, cancellation, or failure.
+ */
+export type TaskGroupGetRunsResponse = TaskRunAPI.TaskRunEvent | TaskRunAPI.ErrorEvent;
+
+export interface TaskGroupCreateParams {
+  /**
+   * User-provided metadata stored with the task group.
+   */
+  metadata?: { [key: string]: string | number | boolean } | null;
+}
+
+export interface TaskGroupAddRunsParams {
+  /**
+   * Body param: List of task runs to execute. Up to 1,000 runs can be specified per
+   * request. If you'd like to add more runs, split them across multiple TaskGroup
+   * POST requests.
+   */
+  inputs: Array<TaskRunAPI.RunInput>;
+
+  /**
+   * Query param
+   */
+  refresh_status?: boolean;
+
+  /**
+   * Body param: Specification for a task.
+   *
+   * Auto output schemas can be specified by setting `output_schema={"type":"auto"}`.
+   * Not specifying a TaskSpec is the same as setting an auto output schema.
+   *
+   * For convenience bare strings are also accepted as input or output schemas.
+   */
+  default_task_spec?: TaskRunAPI.TaskSpec | null;
+
+  /**
+   * Header param: Optional header to specify the beta version(s) to enable.
+   */
+  betas?: Array<BetaTaskRunAPI.ParallelBeta>;
+}
+
+export interface TaskGroupEventsParams {
+  last_event_id?: string | null;
+
+  timeout?: number | null;
+}
+
+export interface TaskGroupGetRunsParams {
+  include_input?: boolean;
+
+  include_output?: boolean;
+
+  last_event_id?: string | null;
+
+  status?:
+    | 'queued'
+    | 'action_required'
+    | 'running'
+    | 'completed'
+    | 'failed'
+    | 'cancelling'
+    | 'cancelled'
+    | null;
+}
+
+export interface TaskGroupRetrieveRunParams {
+  taskgroup_id: string;
+}
+
+export declare namespace TaskGroup {
+  export {
+    type TaskGroup as TaskGroup,
+    type TaskGroupRunResponse as TaskGroupRunResponse,
+    type TaskGroupStatus as TaskGroupStatus,
+    type TaskGroupStatusEvent as TaskGroupStatusEvent,
+    type TaskGroupEventsResponse as TaskGroupEventsResponse,
+    type TaskGroupGetRunsResponse as TaskGroupGetRunsResponse,
+    type TaskGroupCreateParams as TaskGroupCreateParams,
+    type TaskGroupAddRunsParams as TaskGroupAddRunsParams,
+    type TaskGroupEventsParams as TaskGroupEventsParams,
+    type TaskGroupGetRunsParams as TaskGroupGetRunsParams,
+    type TaskGroupRetrieveRunParams as TaskGroupRetrieveRunParams,
+  };
+}

package/src/resources/task-run.ts

@@ -14,7 +14,7 @@ import { path } from '../internal/utils/path';
  * - Output metadata: citations, excerpts, reasoning, and confidence per field
  *
  * Task Groups enable batch execution of many independent Task runs with group-level monitoring and failure handling.
- *  - Submit hundreds or thousands of Tasks as a single group
+ * - Submit hundreds or thousands of Tasks as a single group
  * - Observe group progress and receive results as they complete
  * - Real-time updates via Server-Sent Events (SSE)
  * - Add tasks to an existing group while it is running
@@ -107,6 +107,20 @@ export class TaskRun extends APIResource {
       ]),
     });
   }
+
+  /**
+   * Retrieves the input of a run by run_id.
+   *
+   * @example
+   * ```ts
+   * const runInput = await client.taskRun.retrieveInput(
+   *   'run_id',
+   * );
+   * ```
+   */
+  retrieveInput(runID: string, options?: RequestOptions): APIPromise<RunInput> {
+    return this._client.get(path`/v1/tasks/runs/${runID}/input`, options);
+  }
 }
 
 /**
@@ -278,7 +292,7 @@ export interface RunInput {
   /**
    * Advanced search configuration for a task run.
    */
-  advanced_settings?: RunInput.AdvancedSettings | null;
+  advanced_settings?: TaskAdvancedSettings | null;
 
   /**
    * Controls tracking of task run execution progress. When set to true, progress
@@ -329,16 +343,14 @@ export interface RunInput {
   webhook?: Webhook | null;
 }
 
-export namespace RunInput {
+/**
+ * Advanced search configuration for a task run.
+ */
+export interface TaskAdvancedSettings {
   /**
-   * Advanced search configuration for a task run.
+   * ISO 3166-1 alpha-2 country code for geo-targeted search results.
    */
-  export interface AdvancedSettings {
-    /**
-     * ISO 3166-1 alpha-2 country code for geo-targeted search results.
-     */
-    location?: string | null;
-  }
+  location?: string | null;
 }
 
 /**
@@ -476,6 +488,52 @@ export interface TaskRunJsonOutput {
   output_schema?: { [key: string]: unknown } | null;
 }
 
+/**
+ * A message for a task run progress update.
+ */
+export interface TaskRunProgressMessageEvent {
+  /**
+   * Progress update message.
+   */
+  message: string;
+
+  /**
+   * Timestamp of the message.
+   */
+  timestamp: string | null;
+
+  /**
+   * Event type; always starts with 'task_run.progress_msg'.
+   */
+  type:
+    | 'task_run.progress_msg.plan'
+    | 'task_run.progress_msg.search'
+    | 'task_run.progress_msg.result'
+    | 'task_run.progress_msg.tool_call'
+    | 'task_run.progress_msg.exec_status';
+}
+
+/**
+ * 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 describing progress so far.
+   */
+  source_stats: TaskRunSourceStats;
+
+  /**
+   * Event type; always 'task_run.progress_stats'.
+   */
+  type: 'task_run.progress_stats';
+}
+
 /**
  * Result of a task run.
  */
@@ -491,6 +549,26 @@ export interface TaskRunResult {
   run: TaskRun;
 }
 
+/**
+ * Source stats for a task run.
+ */
+export interface TaskRunSourceStats {
+  /**
+   * Number of sources considered in processing the task.
+   */
+  num_sources_considered: number | null;
+
+  /**
+   * Number of sources read in processing the task.
+   */
+  num_sources_read: number | null;
+
+  /**
+   * A sample of URLs of sources read in processing the task.
+   */
+  sources_read_sample: Array<string> | null;
+}
+
 /**
  * Output from a task that returns text.
  */
@@ -581,81 +659,11 @@ export interface Webhook {
  * A progress update for a task run.
  */
 export type TaskRunEventsResponse =
-  | TaskRunEventsResponse.TaskRunProgressStatsEvent
-  | TaskRunEventsResponse.TaskRunProgressMessageEvent
+  | TaskRunProgressStatsEvent
+  | TaskRunProgressMessageEvent
   | TaskRunEvent
   | ErrorEvent;
 
-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 describing progress so far.
-     */
-    source_stats: TaskRunProgressStatsEvent.SourceStats;
-
-    /**
-     * Event type; always 'task_run.progress_stats'.
-     */
-    type: 'task_run.progress_stats';
-  }
-
-  export namespace TaskRunProgressStatsEvent {
-    /**
-     * Source stats describing progress so far.
-     */
-    export interface SourceStats {
-      /**
-       * Number of sources considered in processing the task.
-       */
-      num_sources_considered: number | null;
-
-      /**
-       * Number of sources read in processing the task.
-       */
-      num_sources_read: number | null;
-
-      /**
-       * A sample of URLs of sources read in processing the task.
-       */
-      sources_read_sample: Array<string> | null;
-    }
-  }
-
-  /**
-   * A message for a task run progress update.
-   */
-  export interface TaskRunProgressMessageEvent {
-    /**
-     * Progress update message.
-     */
-    message: string;
-
-    /**
-     * Timestamp of the message.
-     */
-    timestamp: string | null;
-
-    /**
-     * Event type; always starts with 'task_run.progress_msg'.
-     */
-    type:
-      | 'task_run.progress_msg.plan'
-      | 'task_run.progress_msg.search'
-      | 'task_run.progress_msg.result'
-      | 'task_run.progress_msg.tool_call'
-      | 'task_run.progress_msg.exec_status';
-  }
-}
-
 export interface TaskRunCreateParams {
   /**
    * Body param: Input to the task, either text or a JSON object.
@@ -670,7 +678,7 @@ export interface TaskRunCreateParams {
   /**
    * Body param: Advanced search configuration for a task run.
    */
-  advanced_settings?: TaskRunCreateParams.AdvancedSettings | null;
+  advanced_settings?: TaskAdvancedSettings | null;
 
   /**
    * Body param: Controls tracking of task run execution progress. When set to true,
@@ -726,18 +734,6 @@ export interface TaskRunCreateParams {
   betas?: Array<BetaTaskRunAPI.ParallelBeta>;
 }
 
-export namespace TaskRunCreateParams {
-  /**
-   * Advanced search configuration for a task run.
-   */
-  export interface AdvancedSettings {
-    /**
-     * ISO 3166-1 alpha-2 country code for geo-targeted search results.
-     */
-    location?: string | null;
-  }
-}
-
 export interface TaskRunResultParams {
   /**
    * Query param
@@ -760,10 +756,14 @@ export declare namespace TaskRun {
     type McpServer as McpServer,
     type McpToolCall as McpToolCall,
     type RunInput as RunInput,
+    type TaskAdvancedSettings as TaskAdvancedSettings,
     type TaskRun as TaskRun,
     type TaskRunEvent as TaskRunEvent,
     type TaskRunJsonOutput as TaskRunJsonOutput,
+    type TaskRunProgressMessageEvent as TaskRunProgressMessageEvent,
+    type TaskRunProgressStatsEvent as TaskRunProgressStatsEvent,
     type TaskRunResult as TaskRunResult,
+    type TaskRunSourceStats as TaskRunSourceStats,
     type TaskRunTextOutput as TaskRunTextOutput,
     type TaskSpec as TaskSpec,
     type TextSchema as TextSchema,
@@ -773,3 +773,30 @@ export declare namespace TaskRun {
     type TaskRunResultParams as TaskRunResultParams,
   };
 }
+
+// Backwards-compat namespace members (deprecated). Previously these types
+// existed as nested interfaces under the parent type's namespace; they've
+// since moved to top-level model types. Declaration merging here preserves
+// the old `Parent.Member` import paths.
+type _TaskAdvancedSettings = TaskAdvancedSettings;
+type _TaskRunProgressMessageEvent = TaskRunProgressMessageEvent;
+type _TaskRunProgressStatsEvent = TaskRunProgressStatsEvent;
+type _TaskRunSourceStats = TaskRunSourceStats;
+export namespace RunInput {
+  /** @deprecated Use the top-level `TaskAdvancedSettings` instead. */
+  export type AdvancedSettings = _TaskAdvancedSettings;
+}
+export namespace TaskRunCreateParams {
+  /** @deprecated Use the top-level `TaskAdvancedSettings` instead. */
+  export type AdvancedSettings = _TaskAdvancedSettings;
+}
+export namespace TaskRunEventsResponse {
+  /** @deprecated Use the top-level `TaskRunProgressMessageEvent` instead. */
+  export type TaskRunProgressMessageEvent = _TaskRunProgressMessageEvent;
+  /** @deprecated Use the top-level `TaskRunProgressStatsEvent` instead. */
+  export type TaskRunProgressStatsEvent = _TaskRunProgressStatsEvent;
+  export namespace TaskRunProgressStatsEvent {
+    /** @deprecated Use the top-level `TaskRunSourceStats` instead. */
+    export type SourceStats = _TaskRunSourceStats;
+  }
+}

package/src/resources/top-level.ts

@@ -23,21 +23,7 @@ export interface AdvancedExtractSettings {
    * Controls full content extraction. Set to true to enable with defaults, false to
    * disable, or provide FullContentSettings for fine-grained control.
    */
-  full_content?: AdvancedExtractSettings.FullContentSettings | boolean;
-}
-
-export namespace AdvancedExtractSettings {
-  /**
-   * 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;
-  }
+  full_content?: FullContentSettings | boolean;
 }
 
 /**
@@ -198,6 +184,18 @@ export interface FetchPolicy {
   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;
+}
+
 /**
  * Search response.
  */
@@ -376,6 +374,7 @@ export declare namespace TopLevel {
     type ExtractResponse as ExtractResponse,
     type ExtractResult as ExtractResult,
     type FetchPolicy as FetchPolicy,
+    type FullContentSettings as FullContentSettings,
     type SearchResult as SearchResult,
     type UsageItem as UsageItem,
     type WebSearchResult as WebSearchResult,
@@ -383,3 +382,12 @@ export declare namespace TopLevel {
     type SearchParams as SearchParams,
   };
 }
+
+// Backwards-compat namespace member (deprecated). `AdvancedExtractSettings.FullContentSettings`
+// was previously a nested interface; the shape now lives as the top-level
+// `FullContentSettings` model. Declaration merging here preserves the old path.
+export namespace AdvancedExtractSettings {
+  /** @deprecated Use the top-level `FullContentSettings` instead. */
+  export type FullContentSettings = TopLevelFullContentSettings;
+}
+type TopLevelFullContentSettings = FullContentSettings;

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.4.1'; // x-release-please-version
+export const VERSION = '0.5.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.4.1";
+export declare const VERSION = "0.5.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.4.1'; // x-release-please-version
+exports.VERSION = '0.5.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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