feat(api): Update excerpt settings

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 22
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-70ca78f3dbacd1f8145c633b64c2d9eec9f390db6110ce98705427248a22f19f.yml
-openapi_spec_hash: 877617cbe6e7a48410632dbb57ff5488
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/parallel-web%2Fparallel-sdk-e6afa27fc86492ffa6ee5f929f2d1eb8166750c3a9652a393aede2ca467c49ef.yml
+openapi_spec_hash: 12e9b47405451f5286c199d7ee26c3cc
 config_hash: 6a16116c579cf9a3739083c24b10534d

api.md

@@ -119,15 +119,14 @@ from parallel.types.beta import (
     FindallSchema,
     FindallSchemaUpdatedEvent,
     IngestInput,
-    FindallRetrieveResponse,
     FindallEventsResponse,
 )
 ```
 
 Methods:
 
 - <code title="post /v1beta/findall/runs">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">create</a>(\*\*<a href="src/parallel/types/beta/findall_create_params.py">params</a>) -> <a href="./src/parallel/types/beta/findall_run.py">FindallRun</a></code>
-- <code title="get /v1beta/findall/runs/{findall_id}">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">retrieve</a>(findall_id) -> <a href="./src/parallel/types/beta/findall_retrieve_response.py">FindallRetrieveResponse</a></code>
+- <code title="get /v1beta/findall/runs/{findall_id}">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">retrieve</a>(findall_id) -> <a href="./src/parallel/types/beta/findall_run.py">FindallRun</a></code>
 - <code title="post /v1beta/findall/runs/{findall_id}/cancel">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">cancel</a>(findall_id) -> object</code>
 - <code title="post /v1beta/findall/runs/{findall_id}/enrich">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">enrich</a>(findall_id, \*\*<a href="src/parallel/types/beta/findall_enrich_params.py">params</a>) -> <a href="./src/parallel/types/beta/findall_schema.py">FindallSchema</a></code>
 - <code title="get /v1beta/findall/runs/{findall_id}/events">client.beta.findall.<a href="./src/parallel/resources/beta/findall.py">events</a>(findall_id, \*\*<a href="src/parallel/types/beta/findall_events_params.py">params</a>) -> <a href="./src/parallel/types/beta/findall_events_response.py">FindallEventsResponse</a></code>

src/parallel/resources/beta/beta.py

@@ -90,12 +90,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,
@@ -110,6 +110,8 @@ 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.
@@ -123,8 +125,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
@@ -134,16 +134,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(
@@ -190,7 +184,7 @@ def search(
         `search-extract-2025-10-10`.
 
         Args:
-          excerpts: Optional settings for returning relevant excerpts.
+          excerpts: Optional settings to configure excerpt generation.
 
           fetch_policy: Policy for live fetching web results.
 
@@ -298,12 +292,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,
@@ -318,6 +312,8 @@ 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.
@@ -331,8 +327,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
@@ -342,16 +336,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(
@@ -398,7 +386,7 @@ async def search(
         `search-extract-2025-10-10`.
 
         Args:
-          excerpts: Optional settings for returning relevant excerpts.
+          excerpts: Optional settings to configure excerpt generation.
 
           fetch_policy: Policy for live fetching web results.
 

src/parallel/resources/beta/findall.py

@@ -35,7 +35,6 @@
 from ...types.beta.findall_run_result import FindallRunResult
 from ...types.beta.parallel_beta_param import ParallelBetaParam
 from ...types.beta.findall_events_response import FindallEventsResponse
-from ...types.beta.findall_retrieve_response import FindallRetrieveResponse
 
 __all__ = ["FindallResource", "AsyncFindallResource"]
 
@@ -96,11 +95,12 @@ def create(
         Args:
           entity_type: Type of the entity for the FindAll run.
 
-          generator: Generator for the FindAll run.
+          generator: Generator for the FindAll run. One of base, core, pro, preview.
 
           match_conditions: List of match conditions for the FindAll run.
 
-          match_limit: Maximum number of matches to find for this FindAll run.
+          match_limit: Maximum number of matches to find for this FindAll run. Must be between 5 and
+              1000 (inclusive).
 
           objective: Natural language objective of the FindAll run.
 
@@ -163,7 +163,7 @@ def retrieve(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> FindallRetrieveResponse:
+    ) -> FindallRun:
         """
         Retrieve a FindAll run.
 
@@ -191,17 +191,12 @@ def retrieve(
             **(extra_headers or {}),
         }
         extra_headers = {"parallel-beta": "findall-2025-02-01", **(extra_headers or {})}
-        return cast(
-            FindallRetrieveResponse,
-            self._get(
-                f"/v1beta/findall/runs/{findall_id}",
-                options=make_request_options(
-                    extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
-                ),
-                cast_to=cast(
-                    Any, FindallRetrieveResponse
-                ),  # Union types cannot be passed in as arguments in the type system
+        return self._get(
+            f"/v1beta/findall/runs/{findall_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
+            cast_to=FindallRun,
         )
 
     def cancel(
@@ -270,7 +265,7 @@ def enrich(
         Add an enrichment to a FindAll run.
 
         Args:
-          output_schema: JSON schema for a task input or output.
+          output_schema: JSON schema for the enrichment output schema for the FindAll run.
 
           mcp_servers: List of MCP servers to use for the task.
 
@@ -641,11 +636,12 @@ async def create(
         Args:
           entity_type: Type of the entity for the FindAll run.
 
-          generator: Generator for the FindAll run.
+          generator: Generator for the FindAll run. One of base, core, pro, preview.
 
           match_conditions: List of match conditions for the FindAll run.
 
-          match_limit: Maximum number of matches to find for this FindAll run.
+          match_limit: Maximum number of matches to find for this FindAll run. Must be between 5 and
+              1000 (inclusive).
 
           objective: Natural language objective of the FindAll run.
 
@@ -708,7 +704,7 @@ async def retrieve(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> FindallRetrieveResponse:
+    ) -> FindallRun:
         """
         Retrieve a FindAll run.
 
@@ -736,17 +732,12 @@ async def retrieve(
             **(extra_headers or {}),
         }
         extra_headers = {"parallel-beta": "findall-2025-02-01", **(extra_headers or {})}
-        return cast(
-            FindallRetrieveResponse,
-            await self._get(
-                f"/v1beta/findall/runs/{findall_id}",
-                options=make_request_options(
-                    extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
-                ),
-                cast_to=cast(
-                    Any, FindallRetrieveResponse
-                ),  # Union types cannot be passed in as arguments in the type system
+        return await self._get(
+            f"/v1beta/findall/runs/{findall_id}",
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
+            cast_to=FindallRun,
         )
 
     async def cancel(
@@ -815,7 +806,7 @@ async def enrich(
         Add an enrichment to a FindAll run.
 
         Args:
-          output_schema: JSON schema for a task input or output.
+          output_schema: JSON schema for the enrichment output schema for the FindAll run.
 
           mcp_servers: List of MCP servers to use for the task.
 

src/parallel/types/beta/__init__.py

@@ -42,7 +42,6 @@
 from .task_group_create_params import TaskGroupCreateParams as TaskGroupCreateParams
 from .task_group_events_params import TaskGroupEventsParams as TaskGroupEventsParams
 from .task_run_events_response import TaskRunEventsResponse as TaskRunEventsResponse
-from .findall_retrieve_response import FindallRetrieveResponse as FindallRetrieveResponse
 from .task_group_add_runs_params import TaskGroupAddRunsParams as TaskGroupAddRunsParams
 from .task_group_events_response import TaskGroupEventsResponse as TaskGroupEventsResponse
 from .task_group_get_runs_params import TaskGroupGetRunsParams as TaskGroupGetRunsParams

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.
 
@@ -40,9 +43,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

@@ -17,7 +17,7 @@
 
 class BetaSearchParams(TypedDict, total=False):
     excerpts: ExcerptSettingsParam
-    """Optional settings for returning relevant excerpts."""
+    """Optional settings to configure excerpt generation."""
 
     fetch_policy: Optional[FetchPolicyParam]
     """Policy for live fetching web results."""

src/parallel/types/beta/beta_task_run_result.py

@@ -14,7 +14,11 @@
 
 class OutputBetaTaskRunTextOutput(BaseModel):
     basis: List[FieldBasis]
-    """Basis for the output."""
+    """Basis for the output.
+
+    To include per-list-element basis entries, send the `parallel-beta` header with
+    the value `field-basis-2025-11-25` when creating the run.
+    """
 
     content: str
     """Text output from the task."""
@@ -34,7 +38,11 @@ class OutputBetaTaskRunTextOutput(BaseModel):
 
 class OutputBetaTaskRunJsonOutput(BaseModel):
     basis: List[FieldBasis]
-    """Basis for the output."""
+    """Basis for the output.
+
+    To include per-list-element basis entries, send the `parallel-beta` header with
+    the value `field-basis-2025-11-25` when creating the run.
+    """
 
     content: Dict[str, object]
     """
@@ -71,4 +79,4 @@ class BetaTaskRunResult(BaseModel):
     """Output from the task conforming to the output schema."""
 
     run: TaskRun
-    """Status of a task run."""
+    """Beta task run object with status 'completed'."""

src/parallel/types/beta/error_event.py

@@ -10,7 +10,7 @@
 
 class ErrorEvent(BaseModel):
     error: ErrorObject
-    """An error message."""
+    """Error."""
 
     type: Literal["error"]
     """Event type; always 'error'."""

src/parallel/types/beta/excerpt_settings_param.py

@@ -13,5 +13,13 @@ class ExcerptSettingsParam(TypedDict, total=False):
     """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.
+    token efficiency, but will never contain fewer than 1000 characters per result.
+    """
+
+    max_chars_total: Optional[int]
+    """
+    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.
     """