parallel-web 0.4.1 → 0.5.0

package/resources/task-group.d.ts

@@ -0,0 +1,213 @@
+import { APIResource } from "../core/resource.js";
+import * as TaskRunAPI from "./task-run.js";
+import * as BetaTaskRunAPI from "./beta/task-run.js";
+import { APIPromise } from "../core/api-promise.js";
+import { Stream } from "../core/streaming.js";
+import { RequestOptions } from "../internal/request-options.js";
+/**
+ * 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 declare class TaskGroup extends APIResource {
+    /**
+     * Initiates a TaskGroup to group and track multiple runs.
+     */
+    create(body: TaskGroupCreateParams, options?: RequestOptions): APIPromise<TaskGroup>;
+    /**
+     * Retrieves aggregated status across runs in a TaskGroup.
+     */
+    retrieve(taskGroupID: string, options?: RequestOptions): APIPromise<TaskGroup>;
+    /**
+     * Initiates multiple task runs within a TaskGroup.
+     */
+    addRuns(taskGroupID: string, params: TaskGroupAddRunsParams, options?: RequestOptions): APIPromise<TaskGroupRunResponse>;
+    /**
+     * 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>>;
+    /**
+     * 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>>;
+    /**
+     * 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>;
+}
+/**
+ * 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, };
+}
+//# sourceMappingURL=task-group.d.ts.map

package/resources/task-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-group.d.ts","sourceRoot":"","sources":["../src/resources/task-group.ts"],"names":[],"mappings":"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"}

package/resources/task-group.js

@@ -0,0 +1,95 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskGroup = void 0;
+const resource_1 = require("../core/resource.js");
+const headers_1 = require("../internal/headers.js");
+const path_1 = require("../internal/utils/path.js");
+/**
+ * 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
+ */
+class TaskGroup extends resource_1.APIResource {
+    /**
+     * Initiates a TaskGroup to group and track multiple runs.
+     */
+    create(body, options) {
+        return this._client.post('/v1/tasks/groups', { body, ...options });
+    }
+    /**
+     * Retrieves aggregated status across runs in a TaskGroup.
+     */
+    retrieve(taskGroupID, options) {
+        return this._client.get((0, path_1.path) `/v1/tasks/groups/${taskGroupID}`, options);
+    }
+    /**
+     * Initiates multiple task runs within a TaskGroup.
+     */
+    addRuns(taskGroupID, params, options) {
+        const { refresh_status, betas, ...body } = params;
+        return this._client.post((0, path_1.path) `/v1/tasks/groups/${taskGroupID}/runs`, {
+            query: { refresh_status },
+            body,
+            ...options,
+            headers: (0, headers_1.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, query = {}, options) {
+        return this._client.get((0, path_1.path) `/v1/tasks/groups/${taskGroupID}/events`, {
+            query,
+            ...options,
+            headers: (0, headers_1.buildHeaders)([{ Accept: 'text/event-stream' }, options?.headers]),
+            stream: true,
+        });
+    }
+    /**
+     * 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, query = {}, options) {
+        return this._client.get((0, path_1.path) `/v1/tasks/groups/${taskGroupID}/runs`, {
+            query,
+            ...options,
+            headers: (0, headers_1.buildHeaders)([{ Accept: 'text/event-stream' }, options?.headers]),
+            stream: true,
+        });
+    }
+    /**
+     * 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, params, options) {
+        const { taskgroup_id } = params;
+        return this._client.get((0, path_1.path) `/v1/tasks/groups/${taskgroup_id}/runs/${runID}`, options);
+    }
+}
+exports.TaskGroup = TaskGroup;
+//# sourceMappingURL=task-group.js.map

package/resources/task-group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-group.js","sourceRoot":"","sources":["../src/resources/task-group.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAK/C,oDAAmD;AAEnD,oDAA8C;AAE9C;;;;;;;;;;GAUG;AACH,MAAa,SAAU,SAAQ,sBAAW;IACxC;;OAEG;IACH,MAAM,CAAC,IAA2B,EAAE,OAAwB;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,WAAmB,EAAE,OAAwB;QACpD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,oBAAoB,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAED;;OAEG;IACH,OAAO,CACL,WAAmB,EACnB,MAA8B,EAC9B,OAAwB;QAExB,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAA,WAAI,EAAA,oBAAoB,WAAW,OAAO,EAAE;YACnE,KAAK,EAAE,EAAE,cAAc,EAAE;YACzB,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC;gBACpB,EAAE,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE;gBACvF,OAAO,EAAE,OAAO;aACjB,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,MAAM,CACJ,WAAmB,EACnB,QAA2C,EAAE,EAC7C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,oBAAoB,WAAW,SAAS,EAAE;YACpE,KAAK;YACL,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YAC1E,MAAM,EAAE,IAAI;SACb,CAAgD,CAAC;IACpD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CACL,WAAmB,EACnB,QAA4C,EAAE,EAC9C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,oBAAoB,WAAW,OAAO,EAAE;YAClE,KAAK;YACL,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YAC1E,MAAM,EAAE,IAAI;SACb,CAAiD,CAAC;IACrD,CAAC;IAED;;;;;;;OAOG;IACH,WAAW,CACT,KAAa,EACb,MAAkC,EAClC,OAAwB;QAExB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,oBAAoB,YAAY,SAAS,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;CACF;AA/FD,8BA+FC"}

package/resources/task-group.mjs

@@ -0,0 +1,91 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { APIResource } from "../core/resource.mjs";
+import { buildHeaders } from "../internal/headers.mjs";
+import { path } from "../internal/utils/path.mjs";
+/**
+ * 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, options) {
+        return this._client.post('/v1/tasks/groups', { body, ...options });
+    }
+    /**
+     * Retrieves aggregated status across runs in a TaskGroup.
+     */
+    retrieve(taskGroupID, options) {
+        return this._client.get(path `/v1/tasks/groups/${taskGroupID}`, options);
+    }
+    /**
+     * Initiates multiple task runs within a TaskGroup.
+     */
+    addRuns(taskGroupID, params, options) {
+        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, query = {}, options) {
+        return this._client.get(path `/v1/tasks/groups/${taskGroupID}/events`, {
+            query,
+            ...options,
+            headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
+            stream: true,
+        });
+    }
+    /**
+     * 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, query = {}, options) {
+        return this._client.get(path `/v1/tasks/groups/${taskGroupID}/runs`, {
+            query,
+            ...options,
+            headers: buildHeaders([{ Accept: 'text/event-stream' }, options?.headers]),
+            stream: true,
+        });
+    }
+    /**
+     * 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, params, options) {
+        const { taskgroup_id } = params;
+        return this._client.get(path `/v1/tasks/groups/${taskgroup_id}/runs/${runID}`, options);
+    }
+}
+//# sourceMappingURL=task-group.mjs.map

package/resources/task-group.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-group.mjs","sourceRoot":"","sources":["../src/resources/task-group.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAKf,EAAE,YAAY,EAAE;OAEhB,EAAE,IAAI,EAAE;AAEf;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAU,SAAQ,WAAW;IACxC;;OAEG;IACH,MAAM,CAAC,IAA2B,EAAE,OAAwB;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,WAAmB,EAAE,OAAwB;QACpD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,oBAAoB,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAED;;OAEG;IACH,OAAO,CACL,WAAmB,EACnB,MAA8B,EAC9B,OAAwB;QAExB,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAA,oBAAoB,WAAW,OAAO,EAAE;YACnE,KAAK,EAAE,EAAE,cAAc,EAAE;YACzB,IAAI;YACJ,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC;gBACpB,EAAE,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE;gBACvF,OAAO,EAAE,OAAO;aACjB,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,MAAM,CACJ,WAAmB,EACnB,QAA2C,EAAE,EAC7C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,oBAAoB,WAAW,SAAS,EAAE;YACpE,KAAK;YACL,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YAC1E,MAAM,EAAE,IAAI;SACb,CAAgD,CAAC;IACpD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CACL,WAAmB,EACnB,QAA4C,EAAE,EAC9C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,oBAAoB,WAAW,OAAO,EAAE;YAClE,KAAK;YACL,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YAC1E,MAAM,EAAE,IAAI;SACb,CAAiD,CAAC;IACrD,CAAC;IAED;;;;;;;OAOG;IACH,WAAW,CACT,KAAa,EACb,MAAkC,EAClC,OAAwB;QAExB,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,oBAAoB,YAAY,SAAS,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC;CACF"}

package/resources/task-run.d.mts

@@ -9,7 +9,7 @@ import { RequestOptions } from "../internal/request-options.mjs";
  * - 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
@@ -67,6 +67,17 @@ export declare class TaskRun extends APIResource {
      * ```
      */
     result(runID: string, params?: TaskRunResultParams | null | undefined, options?: RequestOptions): APIPromise<TaskRunResult>;
+    /**
+     * 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>;
 }
 /**
  * Auto schema for a task input or output.
@@ -218,7 +229,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
      * events are recorded and can be accessed via the
@@ -263,16 +274,14 @@ export interface RunInput {
      */
     webhook?: Webhook | null;
 }
-export declare 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.
      */
-    interface AdvancedSettings {
-        /**
-         * ISO 3166-1 alpha-2 country code for geo-targeted search results.
-         */
-        location?: string | null;
-    }
+    location?: string | null;
 }
 /**
  * Status of a task run.
@@ -395,6 +404,41 @@ export interface TaskRunJsonOutput {
         [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.
  */
@@ -408,6 +452,23 @@ 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.
  */
@@ -488,63 +549,7 @@ export interface Webhook {
 /**
  * A progress update for a task run.
  */
-export type TaskRunEventsResponse = TaskRunEventsResponse.TaskRunProgressStatsEvent | TaskRunEventsResponse.TaskRunProgressMessageEvent | TaskRunEvent | ErrorEvent;
-export declare namespace TaskRunEventsResponse {
-    /**
-     * A progress update for a task run.
-     */
-    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';
-    }
-    namespace TaskRunProgressStatsEvent {
-        /**
-         * Source stats describing progress so far.
-         */
-        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.
-     */
-    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 type TaskRunEventsResponse = TaskRunProgressStatsEvent | TaskRunProgressMessageEvent | TaskRunEvent | ErrorEvent;
 export interface TaskRunCreateParams {
     /**
      * Body param: Input to the task, either text or a JSON object.
@@ -559,7 +564,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,
      * progress events are recorded and can be accessed via the
@@ -608,17 +613,6 @@ export interface TaskRunCreateParams {
      */
     betas?: Array<BetaTaskRunAPI.ParallelBeta>;
 }
-export declare namespace TaskRunCreateParams {
-    /**
-     * Advanced search configuration for a task run.
-     */
-    interface AdvancedSettings {
-        /**
-         * ISO 3166-1 alpha-2 country code for geo-targeted search results.
-         */
-        location?: string | null;
-    }
-}
 export interface TaskRunResultParams {
     /**
      * Query param
@@ -630,6 +624,29 @@ export interface TaskRunResultParams {
     betas?: Array<BetaTaskRunAPI.ParallelBeta>;
 }
 export declare namespace TaskRun {
-    export { type AutoSchema as AutoSchema, type Citation as Citation, type ErrorEvent as ErrorEvent, type FieldBasis as FieldBasis, type JsonSchema as JsonSchema, type McpServer as McpServer, type McpToolCall as McpToolCall, type RunInput as RunInput, type TaskRun as TaskRun, type TaskRunEvent as TaskRunEvent, type TaskRunJsonOutput as TaskRunJsonOutput, type TaskRunResult as TaskRunResult, type TaskRunTextOutput as TaskRunTextOutput, type TaskSpec as TaskSpec, type TextSchema as TextSchema, type Webhook as Webhook, type TaskRunEventsResponse as TaskRunEventsResponse, type TaskRunCreateParams as TaskRunCreateParams, type TaskRunResultParams as TaskRunResultParams, };
+    export { type AutoSchema as AutoSchema, type Citation as Citation, type ErrorEvent as ErrorEvent, type FieldBasis as FieldBasis, type JsonSchema as JsonSchema, 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, type Webhook as Webhook, type TaskRunEventsResponse as TaskRunEventsResponse, type TaskRunCreateParams as TaskRunCreateParams, type TaskRunResultParams as TaskRunResultParams, };
+}
+type _TaskAdvancedSettings = TaskAdvancedSettings;
+type _TaskRunProgressMessageEvent = TaskRunProgressMessageEvent;
+type _TaskRunProgressStatsEvent = TaskRunProgressStatsEvent;
+type _TaskRunSourceStats = TaskRunSourceStats;
+export declare namespace RunInput {
+    /** @deprecated Use the top-level `TaskAdvancedSettings` instead. */
+    type AdvancedSettings = _TaskAdvancedSettings;
+}
+export declare namespace TaskRunCreateParams {
+    /** @deprecated Use the top-level `TaskAdvancedSettings` instead. */
+    type AdvancedSettings = _TaskAdvancedSettings;
+}
+export declare namespace TaskRunEventsResponse {
+    /** @deprecated Use the top-level `TaskRunProgressMessageEvent` instead. */
+    type TaskRunProgressMessageEvent = _TaskRunProgressMessageEvent;
+    /** @deprecated Use the top-level `TaskRunProgressStatsEvent` instead. */
+    type TaskRunProgressStatsEvent = _TaskRunProgressStatsEvent;
+    namespace TaskRunProgressStatsEvent {
+        /** @deprecated Use the top-level `TaskRunSourceStats` instead. */
+        type SourceStats = _TaskRunSourceStats;
+    }
 }
+export {};
 //# sourceMappingURL=task-run.d.mts.map