parallel-web 0.3.1 → 0.4.0

package/src/resources/beta/findall.ts

@@ -9,6 +9,9 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
+/**
+ * The FindAll API discovers and evaluates entities that match complex criteria from natural language objectives. Submit a high-level goal and the service automatically generates structured match conditions, discovers relevant candidates, and evaluates each against the criteria. Returns comprehensive results with detailed reasoning, citations, and confidence scores for each match decision. Streaming events and webhooks are supported.
+ */
 export class FindAll extends APIResource {
   /**
    * Starts a FindAll run.
@@ -23,6 +26,23 @@ export class FindAll extends APIResource {
    *   /v1beta/findall/runs/{findall_id}/events endpoint,
    * - Or specifying a webhook with relevant event types during run creation to
    *   receive notifications.
+   *
+   * @example
+   * ```ts
+   * const findallRun = await client.beta.findall.create({
+   *   entity_type: 'entity_type',
+   *   generator: 'base',
+   *   match_conditions: [
+   *     {
+   *       description:
+   *         "Company must have SOC2 Type II certification (not Type I). Look for evidence in: trust centers, security/compliance pages, audit reports, or press releases specifically mentioning 'SOC2 Type II'. If no explicit SOC2 Type II mention is found, consider requirement not satisfied.",
+   *       name: 'name',
+   *     },
+   *   ],
+   *   match_limit: 0,
+   *   objective: 'objective',
+   * });
+   * ```
    */
   create(params: FindAllCreateParams, options?: RequestOptions): APIPromise<FindAllRun> {
     const { betas, ...body } = params;
@@ -38,6 +58,13 @@ export class FindAll extends APIResource {
 
   /**
    * Retrieve a FindAll run.
+   *
+   * @example
+   * ```ts
+   * const findallRun = await client.beta.findall.retrieve(
+   *   'findall_id',
+   * );
+   * ```
    */
   retrieve(
     findallID: string,
@@ -56,6 +83,13 @@ export class FindAll extends APIResource {
 
   /**
    * Cancel a FindAll run.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.findall.cancel(
+   *   'findall_id',
+   * );
+   * ```
    */
   cancel(
     findallID: string,
@@ -72,8 +106,49 @@ export class FindAll extends APIResource {
     });
   }
 
+  /**
+   * Return ranked entity candidates matching a natural language objective.
+   *
+   * This endpoint performs a best-effort search optimised for low latency. For
+   * comprehensive match evaluation and enrichment, use the
+   * [FindAll API](https://docs.parallel.ai/findall-api/findall-quickstart).
+   *
+   * @example
+   * ```ts
+   * const findallCandidatesResponse =
+   *   await client.beta.findall.candidates({
+   *     entity_type: 'company',
+   *     objective: 'objective',
+   *   });
+   * ```
+   */
+  candidates(body: FindAllCandidatesParams, options?: RequestOptions): APIPromise<FindAllCandidatesResponse> {
+    return this._client.post('/v1beta/findall/candidates', {
+      body,
+      ...options,
+      headers: buildHeaders([{ 'parallel-beta': 'findall-2025-09-15' }, options?.headers]),
+    });
+  }
+
   /**
    * Add an enrichment to a FindAll run.
+   *
+   * @example
+   * ```ts
+   * const findallSchema = await client.beta.findall.enrich(
+   *   'findall_id',
+   *   {
+   *     output_schema: {
+   *       json_schema: {
+   *         additionalProperties: 'bar',
+   *         properties: 'bar',
+   *         required: 'bar',
+   *         type: 'bar',
+   *       },
+   *     },
+   *   },
+   * );
+   * ```
    */
   enrich(
     findallID: string,
@@ -98,6 +173,13 @@ export class FindAll extends APIResource {
    * Optional event ID to resume from. timeout: Optional timeout in seconds. If None,
    * keep connection alive as long as the run is going. If set, stop after specified
    * duration.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.findall.events(
+   *   'findall_id',
+   * );
+   * ```
    */
   events(
     findallID: string,
@@ -118,6 +200,14 @@ export class FindAll extends APIResource {
 
   /**
    * Extend a FindAll run by adding additional matches to the current match limit.
+   *
+   * @example
+   * ```ts
+   * const findallSchema = await client.beta.findall.extend(
+   *   'findall_id',
+   *   { additional_match_limit: 0 },
+   * );
+   * ```
    */
   extend(
     findallID: string,
@@ -142,6 +232,14 @@ export class FindAll extends APIResource {
    *
    * The generated specification serves as a suggested starting point and can be
    * further customized by the user.
+   *
+   * @example
+   * ```ts
+   * const findallSchema = await client.beta.findall.ingest({
+   *   objective:
+   *     'Find all AI companies that raised Series A funding in 2024',
+   * });
+   * ```
    */
   ingest(params: FindAllIngestParams, options?: RequestOptions): APIPromise<FindAllSchema> {
     const { betas, ...body } = params;
@@ -157,6 +255,13 @@ export class FindAll extends APIResource {
 
   /**
    * Retrieve the FindAll run result at the time of the request.
+   *
+   * @example
+   * ```ts
+   * const findallRunResult = await client.beta.findall.result(
+   *   'findall_id',
+   * );
+   * ```
    */
   result(
     findallID: string,
@@ -175,6 +280,13 @@ export class FindAll extends APIResource {
 
   /**
    * Get FindAll Run Schema
+   *
+   * @example
+   * ```ts
+   * const findallSchema = await client.beta.findall.schema(
+   *   'findall_id',
+   * );
+   * ```
    */
   schema(
     findallID: string,
@@ -269,6 +381,56 @@ export namespace FindAllCandidateMatchStatusEvent {
   }
 }
 
+export interface FindAllCandidatesRequest {
+  /**
+   * Type of entity to search for.
+   */
+  entity_type: 'company' | 'people';
+
+  /**
+   * Natural language description of target entities.
+   */
+  objective: string;
+
+  /**
+   * Maximum number of candidates to return. Must be between 5 and 1000 (inclusive).
+   * May return fewer results. Defaults to 100.
+   */
+  match_limit?: number;
+}
+
+export interface FindAllCandidatesResponse {
+  /**
+   * Candidate set request ID. Example:
+   * `candidate_set_cad0a6d2dec046bd95ae900527d880e7`
+   */
+  candidate_set_id: string;
+
+  /**
+   * Ranked list of entity candidates.
+   */
+  candidates: Array<FindAllCandidatesResponse.Candidate>;
+}
+
+export namespace FindAllCandidatesResponse {
+  export interface Candidate {
+    /**
+     * Descriptive text about the entity.
+     */
+    description: string;
+
+    /**
+     * Entity name.
+     */
+    name: string;
+
+    /**
+     * Canonical URL for the entity.
+     */
+    url: string;
+  }
+}
+
 /**
  * Input model for FindAll enrich.
  */
@@ -281,7 +443,7 @@ export interface FindAllEnrichInput {
   /**
    * List of MCP servers to use for the task.
    */
-  mcp_servers?: Array<BetaTaskRunAPI.McpServer> | null;
+  mcp_servers?: Array<TaskRunAPI.McpServer> | null;
 
   /**
    * Processor to use for the task.
@@ -367,6 +529,7 @@ export namespace FindAllRun {
       | 'user_cancelled'
       | 'error_occurred'
       | 'timeout'
+      | 'insufficient_funds'
       | null;
   }
 
@@ -409,7 +572,7 @@ export interface FindAllRunInput {
 
   /**
    * Maximum number of matches to find for this FindAll run. Must be between 5 and
-   * 1000 (inclusive).
+   * 1000 (inclusive). May return fewer results.
    */
   match_limit: number;
 
@@ -431,7 +594,7 @@ export interface FindAllRunInput {
   /**
    * Webhooks for Task Runs.
    */
-  webhook?: BetaTaskRunAPI.Webhook | null;
+  webhook?: TaskRunAPI.Webhook | null;
 }
 
 export namespace FindAllRunInput {
@@ -664,7 +827,7 @@ export type FindAllEventsResponse =
   | FindAllSchemaUpdatedEvent
   | FindAllRunStatusEvent
   | FindAllCandidateMatchStatusEvent
-  | BetaTaskRunAPI.ErrorEvent;
+  | TaskRunAPI.ErrorEvent;
 
 export interface FindAllCreateParams {
   /**
@@ -684,7 +847,7 @@ export interface FindAllCreateParams {
 
   /**
    * Body param: Maximum number of matches to find for this FindAll run. Must be
-   * between 5 and 1000 (inclusive).
+   * between 5 and 1000 (inclusive). May return fewer results.
    */
   match_limit: number;
 
@@ -706,7 +869,7 @@ export interface FindAllCreateParams {
   /**
    * Body param: Webhooks for Task Runs.
    */
-  webhook?: BetaTaskRunAPI.Webhook | null;
+  webhook?: TaskRunAPI.Webhook | null;
 
   /**
    * Header param: Optional header to specify the beta version(s) to enable.
@@ -762,6 +925,24 @@ export interface FindAllCancelParams {
   betas?: Array<BetaTaskRunAPI.ParallelBeta>;
 }
 
+export interface FindAllCandidatesParams {
+  /**
+   * Type of entity to search for.
+   */
+  entity_type: 'company' | 'people';
+
+  /**
+   * Natural language description of target entities.
+   */
+  objective: string;
+
+  /**
+   * Maximum number of candidates to return. Must be between 5 and 1000 (inclusive).
+   * May return fewer results. Defaults to 100.
+   */
+  match_limit?: number;
+}
+
 export interface FindAllEnrichParams {
   /**
    * Body param: JSON schema for the enrichment output schema for the FindAll run.
@@ -771,7 +952,7 @@ export interface FindAllEnrichParams {
   /**
    * Body param: List of MCP servers to use for the task.
    */
-  mcp_servers?: Array<BetaTaskRunAPI.McpServer> | null;
+  mcp_servers?: Array<TaskRunAPI.McpServer> | null;
 
   /**
    * Body param: Processor to use for the task.
@@ -844,6 +1025,8 @@ export interface FindAllSchemaParams {
 export declare namespace FindAll {
   export {
     type FindAllCandidateMatchStatusEvent as FindAllCandidateMatchStatusEvent,
+    type FindAllCandidatesRequest as FindAllCandidatesRequest,
+    type FindAllCandidatesResponse as FindAllCandidatesResponse,
     type FindAllEnrichInput as FindAllEnrichInput,
     type FindAllExtendInput as FindAllExtendInput,
     type FindAllRun as FindAllRun,
@@ -858,6 +1041,7 @@ export declare namespace FindAll {
     type FindAllCreateParams as FindAllCreateParams,
     type FindAllRetrieveParams as FindAllRetrieveParams,
     type FindAllCancelParams as FindAllCancelParams,
+    type FindAllCandidatesParams as FindAllCandidatesParams,
     type FindAllEnrichParams as FindAllEnrichParams,
     type FindAllEventsParams as FindAllEventsParams,
     type FindAllExtendParams as FindAllExtendParams,

package/src/resources/beta/index.ts

@@ -5,6 +5,8 @@ export {
   FindAll,
   Findall,
   type FindAllCandidateMatchStatusEvent,
+  type FindAllCandidatesRequest,
+  type FindAllCandidatesResponse,
   type FindAllEnrichInput,
   type FindAllExtendInput,
   type FindAllRun,
@@ -19,6 +21,7 @@ export {
   type FindAllCreateParams,
   type FindAllRetrieveParams,
   type FindAllCancelParams,
+  type FindAllCandidatesParams,
   type FindAllEnrichParams,
   type FindAllEventsParams,
   type FindAllExtendParams,
@@ -60,15 +63,15 @@ export {
 } from './task-group';
 export {
   TaskRun,
+  type ParallelBeta,
+  type TaskRunEventsResponse,
   type BetaRunInput,
   type BetaTaskRunResult,
-  type ErrorEvent,
+  type Webhook,
   type McpServer,
   type McpToolCall,
-  type ParallelBeta,
   type TaskRunEvent,
-  type Webhook,
-  type TaskRunEventsResponse,
+  type ErrorEvent,
   type TaskRunCreateParams,
   type TaskRunResultParams,
 } from './task-run';

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

@@ -10,9 +10,25 @@ 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.
+   *
+   * @example
+   * ```ts
+   * const taskGroup = await client.beta.taskGroup.create();
+   * ```
    */
   create(body: TaskGroupCreateParams, options?: RequestOptions): APIPromise<TaskGroup> {
     return this._client.post('/v1beta/tasks/groups', {
@@ -24,6 +40,13 @@ export class TaskGroup extends APIResource {
 
   /**
    * Retrieves aggregated status across runs in a TaskGroup.
+   *
+   * @example
+   * ```ts
+   * const taskGroup = await client.beta.taskGroup.retrieve(
+   *   'taskgroup_id',
+   * );
+   * ```
    */
   retrieve(taskGroupID: string, options?: RequestOptions): APIPromise<TaskGroup> {
     return this._client.get(path`/v1beta/tasks/groups/${taskGroupID}`, {
@@ -34,14 +57,28 @@ export class TaskGroup extends APIResource {
 
   /**
    * Initiates multiple task runs within a TaskGroup.
+   *
+   * @example
+   * ```ts
+   * const taskGroupRunResponse =
+   *   await client.beta.taskGroup.addRuns('taskgroup_id', {
+   *     inputs: [
+   *       {
+   *         input: 'What was the GDP of France in 2023?',
+   *         processor: 'base',
+   *       },
+   *     ],
+   *   });
+   * ```
    */
   addRuns(
     taskGroupID: string,
     params: TaskGroupAddRunsParams,
     options?: RequestOptions,
   ): APIPromise<TaskGroupRunResponse> {
-    const { betas, ...body } = params;
+    const { refresh_status, betas, ...body } = params;
     return this._client.post(path`/v1beta/tasks/groups/${taskGroupID}/runs`, {
+      query: { refresh_status },
       body,
       ...options,
       headers: buildHeaders([
@@ -56,6 +93,13 @@ export class TaskGroup extends APIResource {
    *
    * The connection will remain open for up to an hour as long as at least one run in
    * the group is still active.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.taskGroup.events(
+   *   'taskgroup_id',
+   * );
+   * ```
    */
   events(
     taskGroupID: string,
@@ -84,6 +128,13 @@ export class TaskGroup extends APIResource {
    * 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`.
+   *
+   * @example
+   * ```ts
+   * const response = await client.beta.taskGroup.getRuns(
+   *   'taskgroup_id',
+   * );
+   * ```
    */
   getRuns(
     taskGroupID: string,
@@ -192,8 +243,8 @@ export interface TaskGroupStatus {
  */
 export type TaskGroupEventsResponse =
   | TaskGroupEventsResponse.TaskGroupStatusEvent
-  | BetaTaskRunAPI.TaskRunEvent
-  | BetaTaskRunAPI.ErrorEvent;
+  | TaskRunAPI.TaskRunEvent
+  | TaskRunAPI.ErrorEvent;
 
 export namespace TaskGroupEventsResponse {
   /**
@@ -222,7 +273,7 @@ export namespace TaskGroupEventsResponse {
  *
  * May indicate completion, cancellation, or failure.
  */
-export type TaskGroupGetRunsResponse = BetaTaskRunAPI.TaskRunEvent | BetaTaskRunAPI.ErrorEvent;
+export type TaskGroupGetRunsResponse = TaskRunAPI.TaskRunEvent | TaskRunAPI.ErrorEvent;
 
 export interface TaskGroupCreateParams {
   /**
@@ -233,9 +284,16 @@ export interface TaskGroupCreateParams {
 
 export interface TaskGroupAddRunsParams {
   /**
-   * Body param: List of task runs to execute.
+   * 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
    */
-  inputs: Array<BetaTaskRunAPI.BetaRunInput>;
+  refresh_status?: boolean;
 
   /**
    * Body param: Specification for a task.