parallel-web 0.3.1 → 0.4.0

package/src/resources/beta/api.md

@@ -0,0 +1,87 @@
+# Beta
+
+Types:
+
+- <code><a href="./src/resources/beta/beta.ts">ExcerptSettings</a></code>
+- <code><a href="./src/resources/beta/beta.ts">ExtractResponse</a></code>
+- <code><a href="./src/resources/beta/beta.ts">ExtractResult</a></code>
+- <code><a href="./src/resources/beta/beta.ts">SearchResult</a></code>
+- <code><a href="./src/resources/beta/beta.ts">WebSearchResult</a></code>
+- <code><a href="./src/resources/beta/beta.ts">ExtractError</a></code>
+- <code><a href="./src/resources/beta/beta.ts">FetchPolicy</a></code>
+- <code><a href="./src/resources/beta/beta.ts">UsageItem</a></code>
+
+Methods:
+
+- <code title="post /v1beta/extract">client.beta.<a href="./src/resources/beta/beta.ts">extract</a>({ ...params }) -> ExtractResponse</code>
+- <code title="post /v1beta/search">client.beta.<a href="./src/resources/beta/beta.ts">search</a>({ ...params }) -> SearchResult</code>
+
+## TaskRun
+
+Types:
+
+- <code><a href="./src/resources/beta/task-run.ts">ParallelBeta</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">TaskRunEventsResponse</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">BetaRunInput</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">BetaTaskRunResult</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">Webhook</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">McpServer</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">McpToolCall</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">TaskRunEvent</a></code>
+- <code><a href="./src/resources/beta/task-run.ts">ErrorEvent</a></code>
+
+Methods:
+
+- <code title="post /v1/tasks/runs">client.beta.taskRun.<a href="./src/resources/beta/task-run.ts">create</a>({ ...params }) -> TaskRun</code>
+- <code title="get /v1beta/tasks/runs/{run_id}/events">client.beta.taskRun.<a href="./src/resources/beta/task-run.ts">events</a>(runID) -> TaskRunEventsResponse</code>
+- <code title="get /v1/tasks/runs/{run_id}/result">client.beta.taskRun.<a href="./src/resources/beta/task-run.ts">result</a>(runID, { ...params }) -> TaskRunResult</code>
+
+## TaskGroup
+
+Types:
+
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroup</a></code>
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroupRunResponse</a></code>
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroupStatus</a></code>
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroupEventsResponse</a></code>
+- <code><a href="./src/resources/beta/task-group.ts">TaskGroupGetRunsResponse</a></code>
+
+Methods:
+
+- <code title="post /v1beta/tasks/groups">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">create</a>({ ...params }) -> TaskGroup</code>
+- <code title="get /v1beta/tasks/groups/{taskgroup_id}">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">retrieve</a>(taskGroupID) -> TaskGroup</code>
+- <code title="post /v1beta/tasks/groups/{taskgroup_id}/runs">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">addRuns</a>(taskGroupID, { ...params }) -> TaskGroupRunResponse</code>
+- <code title="get /v1beta/tasks/groups/{taskgroup_id}/events">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">events</a>(taskGroupID, { ...params }) -> TaskGroupEventsResponse</code>
+- <code title="get /v1beta/tasks/groups/{taskgroup_id}/runs">client.beta.taskGroup.<a href="./src/resources/beta/task-group.ts">getRuns</a>(taskGroupID, { ...params }) -> TaskGroupGetRunsResponse</code>
+
+## FindAll
+
+Types:
+
+- <code><a href="./src/resources/beta/findall.ts">FindAllCandidateMatchStatusEvent</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllCandidatesRequest</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllCandidatesResponse</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllEnrichInput</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllExtendInput</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllRun</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllRunInput</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllRunResult</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllRunStatusEvent</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllSchema</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllSchemaUpdatedEvent</a></code>
+- <code><a href="./src/resources/beta/findall.ts">IngestInput</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllCancelResponse</a></code>
+- <code><a href="./src/resources/beta/findall.ts">FindAllEventsResponse</a></code>
+
+Methods:
+
+- <code title="post /v1beta/findall/runs">client.beta.findall.<a href="./src/resources/beta/findall.ts">create</a>({ ...params }) -> FindAllRun</code>
+- <code title="get /v1beta/findall/runs/{findall_id}">client.beta.findall.<a href="./src/resources/beta/findall.ts">retrieve</a>(findallID, { ...params }) -> FindAllRun</code>
+- <code title="post /v1beta/findall/runs/{findall_id}/cancel">client.beta.findall.<a href="./src/resources/beta/findall.ts">cancel</a>(findallID, { ...params }) -> unknown</code>
+- <code title="post /v1beta/findall/candidates">client.beta.findall.<a href="./src/resources/beta/findall.ts">candidates</a>({ ...params }) -> FindAllCandidatesResponse</code>
+- <code title="post /v1beta/findall/runs/{findall_id}/enrich">client.beta.findall.<a href="./src/resources/beta/findall.ts">enrich</a>(findallID, { ...params }) -> FindAllSchema</code>
+- <code title="get /v1beta/findall/runs/{findall_id}/events">client.beta.findall.<a href="./src/resources/beta/findall.ts">events</a>(findallID, { ...params }) -> FindAllEventsResponse</code>
+- <code title="post /v1beta/findall/runs/{findall_id}/extend">client.beta.findall.<a href="./src/resources/beta/findall.ts">extend</a>(findallID, { ...params }) -> FindAllSchema</code>
+- <code title="post /v1beta/findall/ingest">client.beta.findall.<a href="./src/resources/beta/findall.ts">ingest</a>({ ...params }) -> FindAllSchema</code>
+- <code title="get /v1beta/findall/runs/{findall_id}/result">client.beta.findall.<a href="./src/resources/beta/findall.ts">result</a>(findallID, { ...params }) -> FindAllRunResult</code>
+- <code title="get /v1beta/findall/runs/{findall_id}/schema">client.beta.findall.<a href="./src/resources/beta/findall.ts">schema</a>(findallID, { ...params }) -> FindAllSchema</code>

package/src/resources/beta/beta.ts

@@ -2,12 +2,16 @@
 
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
+import * as TopLevelAPI from '../top-level';
 import * as FindAllAPI from './findall';
 import {
   FindAll,
   FindAllCancelParams,
   FindAllCancelResponse,
   FindAllCandidateMatchStatusEvent,
+  FindAllCandidatesParams,
+  FindAllCandidatesRequest,
+  FindAllCandidatesResponse,
   FindAllCreateParams,
   FindAllEnrichInput,
   FindAllEnrichParams,
@@ -66,8 +70,12 @@ export class Beta extends APIResource {
   /**
    * Extracts relevant content from specific web URLs.
    *
-   * To access this endpoint, pass the `parallel-beta` header with the value
-   * `search-extract-2025-10-10`.
+   * @example
+   * ```ts
+   * const extractResponse = await client.beta.extract({
+   *   urls: ['string'],
+   * });
+   * ```
    */
   extract(params: BetaExtractParams, options?: RequestOptions): APIPromise<ExtractResponse> {
     const { betas, ...body } = params;
@@ -84,8 +92,10 @@ export class Beta extends APIResource {
   /**
    * Searches the web.
    *
-   * To access this endpoint, pass the `parallel-beta` header with the value
-   * `search-extract-2025-10-10`.
+   * @example
+   * ```ts
+   * const searchResult = await client.beta.search();
+   * ```
    */
   search(params: BetaSearchParams, options?: RequestOptions): APIPromise<SearchResult> {
     const { betas, ...body } = params;
@@ -107,41 +117,19 @@ export interface ExcerptSettings {
   /**
    * Optional upper bound on the total number of characters to include per url.
    * Excerpts may contain fewer characters than this limit to maximize relevance and
-   * token efficiency, but will never contain fewer than 1000 characters per result.
+   * token efficiency. Values below 1000 will be automatically set to 1000.
    */
   max_chars_per_result?: number | null;
 
   /**
    * Optional upper bound on the total number of characters to include across all
    * urls. Results may contain fewer characters than this limit to maximize relevance
-   * and token efficiency, but will never contain fewer than 1000 characters per
-   * result.This overall limit applies in addition to max_chars_per_result.
+   * and token efficiency. Values below 1000 will be automatically set to 1000. This
+   * overall limit applies in addition to max_chars_per_result.
    */
   max_chars_total?: 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.
  */
@@ -149,7 +137,7 @@ export interface ExtractResponse {
   /**
    * Extract errors: requested URLs not in the results.
    */
-  errors: Array<ExtractError>;
+  errors: Array<TopLevelAPI.ExtractError>;
 
   /**
    * Extract request ID, e.g. `extract_cad0a6d2dec046bd95ae900527d880e7`
@@ -164,7 +152,7 @@ export interface ExtractResponse {
   /**
    * Usage metrics for the extract request.
    */
-  usage?: Array<UsageItem> | null;
+  usage?: Array<TopLevelAPI.UsageItem> | null;
 
   /**
    * Warnings for the extract request, if any.
@@ -202,28 +190,6 @@ export interface ExtractResult {
   title?: string | null;
 }
 
-/**
- * Policy for live fetching web results.
- */
-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).
-   */
-  max_age_seconds?: number | null;
-
-  /**
-   * Timeout in seconds for fetching live content if unavailable in cache.
-   */
-  timeout_seconds?: number | null;
-}
-
 /**
  * Output for the Search API.
  */
@@ -241,7 +207,7 @@ export interface SearchResult {
   /**
    * Usage metrics for the search request.
    */
-  usage?: Array<UsageItem> | null;
+  usage?: Array<TopLevelAPI.UsageItem> | null;
 
   /**
    * Warnings for the search request, if any.
@@ -249,21 +215,6 @@ export interface SearchResult {
   warnings?: Array<Shared.Warning> | null;
 }
 
-/**
- * Usage item for a single operation.
- */
-export interface UsageItem {
-  /**
-   * Count of the SKU.
-   */
-  count: number;
-
-  /**
-   * Name of the SKU.
-   */
-  name: string;
-}
-
 /**
  * A single search result from the web search API.
  */
@@ -289,6 +240,12 @@ export interface WebSearchResult {
   title?: string | null;
 }
 
+export type ExtractError = TopLevelAPI.ExtractError;
+
+export type FetchPolicy = TopLevelAPI.FetchPolicy;
+
+export type UsageItem = TopLevelAPI.UsageItem;
+
 export interface BetaExtractParams {
   /**
    * Body param
@@ -305,7 +262,7 @@ export interface BetaExtractParams {
   /**
    * Body param: Policy for live fetching web results.
    */
-  fetch_policy?: FetchPolicy | null;
+  fetch_policy?: TopLevelAPI.FetchPolicy | null;
 
   /**
    * Body param: Include full content from each URL. Note that if neither objective
@@ -325,6 +282,13 @@ export interface BetaExtractParams {
    */
   search_queries?: Array<string> | null;
 
+  /**
+   * Body param: Session identifier to track calls across separate search and extract
+   * calls, to be used as part of a larger task. Specifying it may give better
+   * contextual results for subsequent API calls.
+   */
+  session_id?: string | null;
+
   /**
    * Header param: Optional header to specify the beta version(s) to enable.
    */
@@ -354,7 +318,12 @@ export interface BetaSearchParams {
   /**
    * Body param: Policy for live fetching web results.
    */
-  fetch_policy?: FetchPolicy | null;
+  fetch_policy?: TopLevelAPI.FetchPolicy | null;
+
+  /**
+   * Body param: ISO 3166-1 alpha-2 country code for geo-targeted search results.
+   */
+  location?: string | null;
 
   /**
    * @deprecated Body param: DEPRECATED: Use `excerpts.max_chars_per_result` instead.
@@ -362,18 +331,22 @@ export interface BetaSearchParams {
   max_chars_per_result?: number | null;
 
   /**
-   * Body param: 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. Defaults to 10 if
+   * not provided.
    */
   max_results?: number | null;
 
   /**
    * Body param: Presets default values for parameters for different use cases.
-   * `one-shot` returns more comprehensive results and longer excerpts to answer
-   * questions from a single response, while `agentic` returns more concise,
-   * token-efficient results for use in an agentic loop.
+   *
+   * - `one-shot` returns more comprehensive results and longer excerpts to answer
+   *   questions from a single response
+   * - `agentic` returns more concise, token-efficient results for use in an agentic
+   *   loop
+   * - `fast` trades some quality for lower latency, with best results when used with
+   *   concise and high-quality objective and keyword queries
    */
-  mode?: 'one-shot' | 'agentic' | null;
+  mode?: 'one-shot' | 'agentic' | 'fast' | null;
 
   /**
    * Body param: Natural-language description of what the web search is trying to
@@ -394,6 +367,13 @@ export interface BetaSearchParams {
    */
   search_queries?: Array<string> | null;
 
+  /**
+   * Body param: Session identifier to track calls across separate search and extract
+   * calls, to be used as part of a larger task. Specifying it may give better
+   * contextual results for subsequent API calls.
+   */
+  session_id?: string | null;
+
   /**
    * Body param: Source policy for web search results.
    *
@@ -413,28 +393,28 @@ Beta.FindAll = FindAll;
 export declare namespace Beta {
   export {
     type ExcerptSettings as ExcerptSettings,
-    type ExtractError as ExtractError,
     type ExtractResponse as ExtractResponse,
     type ExtractResult as ExtractResult,
-    type FetchPolicy as FetchPolicy,
     type SearchResult as SearchResult,
-    type UsageItem as UsageItem,
     type WebSearchResult as WebSearchResult,
+    type ExtractError as ExtractError,
+    type FetchPolicy as FetchPolicy,
+    type UsageItem as UsageItem,
     type BetaExtractParams as BetaExtractParams,
     type BetaSearchParams as BetaSearchParams,
   };
 
   export {
     TaskRun as TaskRun,
+    type ParallelBeta as ParallelBeta,
+    type TaskRunEventsResponse as TaskRunEventsResponse,
     type BetaRunInput as BetaRunInput,
     type BetaTaskRunResult as BetaTaskRunResult,
-    type ErrorEvent as ErrorEvent,
+    type Webhook as Webhook,
     type McpServer as McpServer,
     type McpToolCall as McpToolCall,
-    type ParallelBeta as ParallelBeta,
     type TaskRunEvent as TaskRunEvent,
-    type Webhook as Webhook,
-    type TaskRunEventsResponse as TaskRunEventsResponse,
+    type ErrorEvent as ErrorEvent,
     type TaskRunCreateParams as TaskRunCreateParams,
     type TaskRunResultParams as TaskRunResultParams,
   };
@@ -454,6 +434,8 @@ export declare namespace Beta {
   export {
     FindAll as FindAll,
     type FindAllCandidateMatchStatusEvent as FindAllCandidateMatchStatusEvent,
+    type FindAllCandidatesRequest as FindAllCandidatesRequest,
+    type FindAllCandidatesResponse as FindAllCandidatesResponse,
     type FindAllEnrichInput as FindAllEnrichInput,
     type FindAllExtendInput as FindAllExtendInput,
     type FindAllRun as FindAllRun,
@@ -468,6 +450,7 @@ export declare namespace Beta {
     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,