feat(api): add fetch_policy and mode to /v1beta/search

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 13
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-9ec04ca53245a774513f3e178c29a560d6ecb3f88f936859e6311bf0d4ad1fb2.yml
-openapi_spec_hash: 022ed0f0e4ad23fd88f8d3a8fe003e14
-config_hash: 5c1316cf65d52fe3b23d4fe7acbb4baf
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-40c12295a3f32ed93d58b523bb28f33ceabe8e6bfa8c44d5f863ed9c77feff58.yml
+openapi_spec_hash: 9f3cd99867507ada834db61c6d8391b9
+config_hash: 677d555754b79eb922f6bf64bccd9559

api.md

@@ -47,6 +47,7 @@ from parallel.types.beta import (
     ExtractResult,
     FetchPolicy,
     SearchResult,
+    UsageItem,
     WebSearchResult,
 )
 ```

src/parallel/resources/beta/beta.py

@@ -40,6 +40,7 @@
 from ...types.beta.extract_response import ExtractResponse
 from ...types.beta.fetch_policy_param import FetchPolicyParam
 from ...types.beta.parallel_beta_param import ParallelBetaParam
+from ...types.beta.excerpt_settings_param import ExcerptSettingsParam
 from ...types.shared_params.source_policy import SourcePolicy
 
 __all__ = ["BetaResource", "AsyncBetaResource"]
@@ -77,12 +78,12 @@ def extract(
         self,
         *,
         urls: SequenceNotStr[str],
+        betas: List[ParallelBetaParam],
         excerpts: beta_extract_params.Excerpts | Omit = omit,
         fetch_policy: Optional[FetchPolicyParam] | Omit = omit,
         full_content: beta_extract_params.FullContent | Omit = omit,
         objective: Optional[str] | Omit = omit,
         search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
-        betas: List[ParallelBetaParam] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -97,14 +98,17 @@ def extract(
         `search-extract-2025-10-10`.
 
         Args:
+          betas: Optional header to specify the beta version(s) to enable.
+
           excerpts: 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.
 
-          fetch_policy: Fetch policy.
+          fetch_policy: Policy for live fetching web results.
 
-              Determines when to return content from the cache (faster) vs fetching live
-              content (fresher).
+              Determines when to return cached content from the index (faster) vs fetching
+              live content (fresher). The default policy for search uses cached results only,
+              while extract uses a dynamic policy based on the search objective and url.
 
           full_content: Include full content from each URL. Note that if neither objective nor
               search_queries is provided, excerpts are redundant with full content.
@@ -113,8 +117,6 @@ def extract(
 
           search_queries: If provided, focuses extracted content on the specified keyword search queries.
 
-          betas: Optional header to specify the beta version(s) to enable.
-
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -124,16 +126,10 @@ def extract(
           timeout: Override the client-level default timeout for this request, in seconds
         """
         extra_headers = {
-            **strip_not_given(
-                {
-                    "parallel-beta": ",".join(chain((str(e) for e in betas), ["search-extract-2025-10-10"]))
-                    if is_given(betas)
-                    else not_given
-                }
-            ),
+            "parallel-beta": ",".join(chain((str(e) for e in betas), ["search-extract-2025-10-10"])),
             **(extra_headers or {}),
         }
-        extra_headers = {"parallel-beta": "search-extract-2025-10-10", **(extra_headers or {})}
+        extra_headers.update({"parallel-beta": "search-extract-2025-10-10"})
         return self._post(
             "/v1beta/extract",
             body=maybe_transform(
@@ -156,10 +152,11 @@ def extract(
     def search(
         self,
         *,
-        max_chars_per_result: Optional[int] | Omit = omit,
+        excerpts: ExcerptSettingsParam | Omit = omit,
+        fetch_policy: Optional[FetchPolicyParam] | Omit = omit,
         max_results: Optional[int] | Omit = omit,
+        mode: Optional[Literal["one-shot", "agentic"]] | Omit = omit,
         objective: Optional[str] | Omit = omit,
-        processor: Optional[Literal["base", "pro"]] | Omit = omit,
         search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
         source_policy: Optional[SourcePolicy] | Omit = omit,
         betas: List[ParallelBetaParam] | Omit = omit,
@@ -173,19 +170,30 @@ def search(
         """
         Searches the web.
 
+        To access this endpoint, pass the `parallel-beta` header with the value
+        `search-extract-2025-10-10`.
+
         Args:
-          max_chars_per_result: Upper bound on the number of characters to include in excerpts for each search
-              result.
+          excerpts: Optional settings for returning relevant excerpts.
+
+          fetch_policy: Policy for live fetching web results.
+
+              Determines when to return cached content from the index (faster) vs fetching
+              live content (fresher). The default policy for search uses cached results only,
+              while extract uses a dynamic policy based on the search objective and url.
 
           max_results: Upper bound on the number of results to return. May be limited by the processor.
               Defaults to 10 if not provided.
 
+          mode: 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.
+
           objective: 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.
 
-          processor: Search processor.
-
           search_queries: 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.
@@ -219,10 +227,11 @@ def search(
             "/v1beta/search",
             body=maybe_transform(
                 {
-                    "max_chars_per_result": max_chars_per_result,
+                    "excerpts": excerpts,
+                    "fetch_policy": fetch_policy,
                     "max_results": max_results,
+                    "mode": mode,
                     "objective": objective,
-                    "processor": processor,
                     "search_queries": search_queries,
                     "source_policy": source_policy,
                 },
@@ -267,12 +276,12 @@ async def extract(
         self,
         *,
         urls: SequenceNotStr[str],
+        betas: List[ParallelBetaParam],
         excerpts: beta_extract_params.Excerpts | Omit = omit,
         fetch_policy: Optional[FetchPolicyParam] | Omit = omit,
         full_content: beta_extract_params.FullContent | Omit = omit,
         objective: Optional[str] | Omit = omit,
         search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
-        betas: List[ParallelBetaParam] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -287,14 +296,17 @@ async def extract(
         `search-extract-2025-10-10`.
 
         Args:
+          betas: Optional header to specify the beta version(s) to enable.
+
           excerpts: 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.
 
-          fetch_policy: Fetch policy.
+          fetch_policy: Policy for live fetching web results.
 
-              Determines when to return content from the cache (faster) vs fetching live
-              content (fresher).
+              Determines when to return cached content from the index (faster) vs fetching
+              live content (fresher). The default policy for search uses cached results only,
+              while extract uses a dynamic policy based on the search objective and url.
 
           full_content: Include full content from each URL. Note that if neither objective nor
               search_queries is provided, excerpts are redundant with full content.
@@ -303,8 +315,6 @@ async def extract(
 
           search_queries: If provided, focuses extracted content on the specified keyword search queries.
 
-          betas: Optional header to specify the beta version(s) to enable.
-
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -314,16 +324,10 @@ async def extract(
           timeout: Override the client-level default timeout for this request, in seconds
         """
         extra_headers = {
-            **strip_not_given(
-                {
-                    "parallel-beta": ",".join(chain((str(e) for e in betas), ["search-extract-2025-10-10"]))
-                    if is_given(betas)
-                    else not_given
-                }
-            ),
+            "parallel-beta": ",".join(chain((str(e) for e in betas), ["search-extract-2025-10-10"])),
             **(extra_headers or {}),
         }
-        extra_headers = {"parallel-beta": "search-extract-2025-10-10", **(extra_headers or {})}
+        extra_headers.update({"parallel-beta": "search-extract-2025-10-10"})
         return await self._post(
             "/v1beta/extract",
             body=await async_maybe_transform(
@@ -346,10 +350,11 @@ async def extract(
     async def search(
         self,
         *,
-        max_chars_per_result: Optional[int] | Omit = omit,
+        excerpts: ExcerptSettingsParam | Omit = omit,
+        fetch_policy: Optional[FetchPolicyParam] | Omit = omit,
         max_results: Optional[int] | Omit = omit,
+        mode: Optional[Literal["one-shot", "agentic"]] | Omit = omit,
         objective: Optional[str] | Omit = omit,
-        processor: Optional[Literal["base", "pro"]] | Omit = omit,
         search_queries: Optional[SequenceNotStr[str]] | Omit = omit,
         source_policy: Optional[SourcePolicy] | Omit = omit,
         betas: List[ParallelBetaParam] | Omit = omit,
@@ -363,19 +368,30 @@ async def search(
         """
         Searches the web.
 
+        To access this endpoint, pass the `parallel-beta` header with the value
+        `search-extract-2025-10-10`.
+
         Args:
-          max_chars_per_result: Upper bound on the number of characters to include in excerpts for each search
-              result.
+          excerpts: Optional settings for returning relevant excerpts.
+
+          fetch_policy: Policy for live fetching web results.
+
+              Determines when to return cached content from the index (faster) vs fetching
+              live content (fresher). The default policy for search uses cached results only,
+              while extract uses a dynamic policy based on the search objective and url.
 
           max_results: Upper bound on the number of results to return. May be limited by the processor.
               Defaults to 10 if not provided.
 
+          mode: 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.
+
           objective: 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.
 
-          processor: Search processor.
-
           search_queries: 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.
@@ -409,10 +425,11 @@ async def search(
             "/v1beta/search",
             body=await async_maybe_transform(
                 {
-                    "max_chars_per_result": max_chars_per_result,
+                    "excerpts": excerpts,
+                    "fetch_policy": fetch_policy,
                     "max_results": max_results,
+                    "mode": mode,
                     "objective": objective,
-                    "processor": processor,
                     "search_queries": search_queries,
                     "source_policy": source_policy,
                 },

src/parallel/types/beta/__init__.py

@@ -5,6 +5,7 @@
 from .webhook import Webhook as Webhook
 from .mcp_server import McpServer as McpServer
 from .task_group import TaskGroup as TaskGroup
+from .usage_item import UsageItem as UsageItem
 from .error_event import ErrorEvent as ErrorEvent
 from .extract_error import ExtractError as ExtractError
 from .mcp_tool_call import McpToolCall as McpToolCall

src/parallel/types/beta/beta_extract_params.py

@@ -17,6 +17,9 @@
 class BetaExtractParams(TypedDict, total=False):
     urls: Required[SequenceNotStr[str]]
 
+    betas: Required[Annotated[List[ParallelBetaParam], PropertyInfo(alias="parallel-beta")]]
+    """Optional header to specify the beta version(s) to enable."""
+
     excerpts: Excerpts
     """Include excerpts from each URL relevant to the search objective and queries.
 
@@ -25,10 +28,11 @@ class BetaExtractParams(TypedDict, total=False):
     """
 
     fetch_policy: Optional[FetchPolicyParam]
-    """Fetch policy.
+    """Policy for live fetching web results.
 
-    Determines when to return content from the cache (faster) vs fetching live
-    content (fresher).
+    Determines when to return cached content from the index (faster) vs fetching
+    live content (fresher). The default policy for search uses cached results only,
+    while extract uses a dynamic policy based on the search objective and url.
     """
 
     full_content: FullContent
@@ -44,9 +48,6 @@ class BetaExtractParams(TypedDict, total=False):
     search_queries: Optional[SequenceNotStr[str]]
     """If provided, focuses extracted content on the specified keyword search queries."""
 
-    betas: Annotated[List[ParallelBetaParam], PropertyInfo(alias="parallel-beta")]
-    """Optional header to specify the beta version(s) to enable."""
-
 
 Excerpts: TypeAlias = Union[bool, ExcerptSettingsParam]
 

src/parallel/types/beta/beta_search_params.py

@@ -7,17 +7,24 @@
 
 from ..._types import SequenceNotStr
 from ..._utils import PropertyInfo
+from .fetch_policy_param import FetchPolicyParam
 from .parallel_beta_param import ParallelBetaParam
+from .excerpt_settings_param import ExcerptSettingsParam
 from ..shared_params.source_policy import SourcePolicy
 
 __all__ = ["BetaSearchParams"]
 
 
 class BetaSearchParams(TypedDict, total=False):
-    max_chars_per_result: Optional[int]
-    """
-    Upper bound on the number of characters to include in excerpts for each search
-    result.
+    excerpts: ExcerptSettingsParam
+    """Optional settings for returning relevant excerpts."""
+
+    fetch_policy: Optional[FetchPolicyParam]
+    """Policy for live fetching web results.
+
+    Determines when to return cached content from the index (faster) vs fetching
+    live content (fresher). The default policy for search uses cached results only,
+    while extract uses a dynamic policy based on the search objective and url.
     """
 
     max_results: Optional[int]
@@ -26,16 +33,21 @@ class BetaSearchParams(TypedDict, total=False):
     May be limited by the processor. Defaults to 10 if not provided.
     """
 
+    mode: Optional[Literal["one-shot", "agentic"]]
+    """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.
+    """
+
     objective: Optional[str]
     """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.
     """
 
-    processor: Optional[Literal["base", "pro"]]
-    """Search processor."""
-
     search_queries: Optional[SequenceNotStr[str]]
     """Optional list of traditional keyword search queries to guide the search.
 

src/parallel/types/beta/excerpt_settings_param.py

@@ -10,8 +10,8 @@
 
 class ExcerptSettingsParam(TypedDict, total=False):
     max_chars_per_result: Optional[int]
-    """
-    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.
+    """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.
     """