release: 0.35.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.34.1"
+  ".": "0.35.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 10
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/perplexity-ai/perplexity-fcf27eaa172b35187bd87aa80b4d18e2b05c5a8544734d56bd4079064bec4bb4.yml
-openapi_spec_hash: 35a516eefbd34cf6620a114bf28c27a5
-config_hash: 86d643a5df0d7478c095d3efa13438dd
+configured_endpoints: 11
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/perplexity-ai/perplexity-fff71875865f090e567436080392bfe633cefac2a82f5eba143ca6fcfed86a56.yml
+openapi_spec_hash: 2cb780b456c70cbdcb1ba0182f424c9b
+config_hash: 059988c88f0dc18e9e393daed94b5eb6

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.35.0 (2026-05-27)
+
+Full Changelog: [v0.34.1...v0.35.0](https://github.com/perplexityai/perplexity-py/compare/v0.34.1...v0.35.0)
+
+### Features
+
+* **api:** search_context_size, background tasks, reasoning effort xhigh + responses.retrieve ([93027f5](https://github.com/perplexityai/perplexity-py/commit/93027f5e57e40a6ca07004281c58d5d86c9607b7))
+
 ## 0.34.1 (2026-05-27)
 
 Full Changelog: [v0.34.0...v0.34.1](https://github.com/perplexityai/perplexity-py/compare/v0.34.0...v0.34.1)

api.md

@@ -62,12 +62,14 @@ from perplexity.types import (
     ResponseCreateParams,
     ResponsesUsage,
     ResponseCreateResponse,
+    ResponseRetrieveResponse,
 )
 ```
 
 Methods:
 
 - <code title="post /v1/responses">client.responses.<a href="./src/perplexity/resources/responses.py">create</a>(\*\*<a href="src/perplexity/types/response_create_params.py">params</a>) -> <a href="./src/perplexity/types/response_create_response.py">ResponseCreateResponse</a></code>
+- <code title="get /v1/responses/{response_id}">client.responses.<a href="./src/perplexity/resources/responses.py">retrieve</a>(response_id) -> <a href="./src/perplexity/types/response_retrieve_response.py">ResponseRetrieveResponse</a></code>
 
 # Embeddings
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "perplexityai"
-version = "0.34.1"
+version = "0.35.0"
 description = "The official Python library for the perplexity API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/perplexity/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "perplexity"
-__version__ = "0.34.1"  # x-release-please-version
+__version__ = "0.35.0"  # x-release-please-version

src/perplexity/resources/responses.py

@@ -2,14 +2,14 @@
 
 from __future__ import annotations
 
-from typing import Union, Iterable
+from typing import Union, Iterable, Optional
 from typing_extensions import Literal, overload
 
 import httpx
 
 from ..types import response_create_params
 from .._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
-from .._utils import required_args, maybe_transform, async_maybe_transform
+from .._utils import path_template, required_args, maybe_transform, async_maybe_transform
 from .._compat import cached_property
 from .._resource import SyncAPIResource, AsyncAPIResource
 from .._response import (
@@ -23,6 +23,7 @@
 from ..types.input_item_param import InputItemParam
 from ..types.response_stream_chunk import ResponseStreamChunk
 from ..types.response_create_response import ResponseCreateResponse
+from ..types.response_retrieve_response import ResponseRetrieveResponse
 from ..types.shared_params.response_format import ResponseFormat
 
 __all__ = ["ResponsesResource", "AsyncResponsesResource"]
@@ -53,6 +54,7 @@ def create(
         self,
         *,
         input: Union[str, Iterable[InputItemParam]],
+        background: Optional[bool] | Omit = omit,
         instructions: str | Omit = omit,
         language_preference: str | Omit = omit,
         max_output_tokens: int | Omit = omit,
@@ -78,6 +80,10 @@ def create(
         Args:
           input: Input content - either a string or array of input items
 
+          background: Run the response asynchronously. When true, the request is queued and the
+              response object's `status` will be `queued` or `in_progress`. Poll GET
+              /v1/responses/{response_id} to retrieve the final result.
+
           instructions: System instructions for the model
 
           language_preference: ISO 639-1 language code for response language
@@ -122,6 +128,7 @@ def create(
         *,
         input: Union[str, Iterable[InputItemParam]],
         stream: Literal[True],
+        background: Optional[bool] | Omit = omit,
         instructions: str | Omit = omit,
         language_preference: str | Omit = omit,
         max_output_tokens: int | Omit = omit,
@@ -148,6 +155,10 @@ def create(
 
           stream: If true, returns SSE stream instead of JSON
 
+          background: Run the response asynchronously. When true, the request is queued and the
+              response object's `status` will be `queued` or `in_progress`. Poll GET
+              /v1/responses/{response_id} to retrieve the final result.
+
           instructions: System instructions for the model
 
           language_preference: ISO 639-1 language code for response language
@@ -190,6 +201,7 @@ def create(
         *,
         input: Union[str, Iterable[InputItemParam]],
         stream: bool,
+        background: Optional[bool] | Omit = omit,
         instructions: str | Omit = omit,
         language_preference: str | Omit = omit,
         max_output_tokens: int | Omit = omit,
@@ -216,6 +228,10 @@ def create(
 
           stream: If true, returns SSE stream instead of JSON
 
+          background: Run the response asynchronously. When true, the request is queued and the
+              response object's `status` will be `queued` or `in_progress`. Poll GET
+              /v1/responses/{response_id} to retrieve the final result.
+
           instructions: System instructions for the model
 
           language_preference: ISO 639-1 language code for response language
@@ -257,6 +273,7 @@ def create(
         self,
         *,
         input: Union[str, Iterable[InputItemParam]],
+        background: Optional[bool] | Omit = omit,
         instructions: str | Omit = omit,
         language_preference: str | Omit = omit,
         max_output_tokens: int | Omit = omit,
@@ -280,6 +297,7 @@ def create(
             body=maybe_transform(
                 {
                     "input": input,
+                    "background": background,
                     "instructions": instructions,
                     "language_preference": language_preference,
                     "max_output_tokens": max_output_tokens,
@@ -304,6 +322,40 @@ def create(
             stream_cls=Stream[ResponseStreamChunk],
         )
 
+    def retrieve(
+        self,
+        response_id: str,
+        *,
+        # 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,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> ResponseRetrieveResponse:
+        """Retrieve a response by its ID.
+
+        Use this to poll the status of background tasks.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not response_id:
+            raise ValueError(f"Expected a non-empty value for `response_id` but received {response_id!r}")
+        return self._get(
+            path_template("/v1/responses/{response_id}", response_id=response_id),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ResponseRetrieveResponse,
+        )
+
 
 class AsyncResponsesResource(AsyncAPIResource):
     @cached_property
@@ -330,6 +382,7 @@ async def create(
         self,
         *,
         input: Union[str, Iterable[InputItemParam]],
+        background: Optional[bool] | Omit = omit,
         instructions: str | Omit = omit,
         language_preference: str | Omit = omit,
         max_output_tokens: int | Omit = omit,
@@ -355,6 +408,10 @@ async def create(
         Args:
           input: Input content - either a string or array of input items
 
+          background: Run the response asynchronously. When true, the request is queued and the
+              response object's `status` will be `queued` or `in_progress`. Poll GET
+              /v1/responses/{response_id} to retrieve the final result.
+
           instructions: System instructions for the model
 
           language_preference: ISO 639-1 language code for response language
@@ -399,6 +456,7 @@ async def create(
         *,
         input: Union[str, Iterable[InputItemParam]],
         stream: Literal[True],
+        background: Optional[bool] | Omit = omit,
         instructions: str | Omit = omit,
         language_preference: str | Omit = omit,
         max_output_tokens: int | Omit = omit,
@@ -425,6 +483,10 @@ async def create(
 
           stream: If true, returns SSE stream instead of JSON
 
+          background: Run the response asynchronously. When true, the request is queued and the
+              response object's `status` will be `queued` or `in_progress`. Poll GET
+              /v1/responses/{response_id} to retrieve the final result.
+
           instructions: System instructions for the model
 
           language_preference: ISO 639-1 language code for response language
@@ -467,6 +529,7 @@ async def create(
         *,
         input: Union[str, Iterable[InputItemParam]],
         stream: bool,
+        background: Optional[bool] | Omit = omit,
         instructions: str | Omit = omit,
         language_preference: str | Omit = omit,
         max_output_tokens: int | Omit = omit,
@@ -493,6 +556,10 @@ async def create(
 
           stream: If true, returns SSE stream instead of JSON
 
+          background: Run the response asynchronously. When true, the request is queued and the
+              response object's `status` will be `queued` or `in_progress`. Poll GET
+              /v1/responses/{response_id} to retrieve the final result.
+
           instructions: System instructions for the model
 
           language_preference: ISO 639-1 language code for response language
@@ -534,6 +601,7 @@ async def create(
         self,
         *,
         input: Union[str, Iterable[InputItemParam]],
+        background: Optional[bool] | Omit = omit,
         instructions: str | Omit = omit,
         language_preference: str | Omit = omit,
         max_output_tokens: int | Omit = omit,
@@ -557,6 +625,7 @@ async def create(
             body=await async_maybe_transform(
                 {
                     "input": input,
+                    "background": background,
                     "instructions": instructions,
                     "language_preference": language_preference,
                     "max_output_tokens": max_output_tokens,
@@ -581,6 +650,40 @@ async def create(
             stream_cls=AsyncStream[ResponseStreamChunk],
         )
 
+    async def retrieve(
+        self,
+        response_id: str,
+        *,
+        # 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,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> ResponseRetrieveResponse:
+        """Retrieve a response by its ID.
+
+        Use this to poll the status of background tasks.
+
+        Args:
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not response_id:
+            raise ValueError(f"Expected a non-empty value for `response_id` but received {response_id!r}")
+        return await self._get(
+            path_template("/v1/responses/{response_id}", response_id=response_id),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=ResponseRetrieveResponse,
+        )
+
 
 class ResponsesResourceWithRawResponse:
     def __init__(self, responses: ResponsesResource) -> None:
@@ -589,6 +692,9 @@ def __init__(self, responses: ResponsesResource) -> None:
         self.create = to_raw_response_wrapper(
             responses.create,
         )
+        self.retrieve = to_raw_response_wrapper(
+            responses.retrieve,
+        )
 
 
 class AsyncResponsesResourceWithRawResponse:
@@ -598,6 +704,9 @@ def __init__(self, responses: AsyncResponsesResource) -> None:
         self.create = async_to_raw_response_wrapper(
             responses.create,
         )
+        self.retrieve = async_to_raw_response_wrapper(
+            responses.retrieve,
+        )
 
 
 class ResponsesResourceWithStreamingResponse:
@@ -607,6 +716,9 @@ def __init__(self, responses: ResponsesResource) -> None:
         self.create = to_streamed_response_wrapper(
             responses.create,
         )
+        self.retrieve = to_streamed_response_wrapper(
+            responses.retrieve,
+        )
 
 
 class AsyncResponsesResourceWithStreamingResponse:
@@ -616,3 +728,6 @@ def __init__(self, responses: AsyncResponsesResource) -> None:
         self.create = async_to_streamed_response_wrapper(
             responses.create,
         )
+        self.retrieve = async_to_streamed_response_wrapper(
+            responses.retrieve,
+        )

src/perplexity/resources/search.py

@@ -57,6 +57,7 @@ def create(
         max_tokens_per_page: int | Omit = omit,
         search_after_date_filter: Optional[str] | Omit = omit,
         search_before_date_filter: Optional[str] | Omit = omit,
+        search_context_size: Optional[Literal["low", "medium", "high"]] | Omit = omit,
         search_domain_filter: Optional[SequenceNotStr[str]] | Omit = omit,
         search_language_filter: Optional[SequenceNotStr[str]] | Omit = omit,
         search_mode: Optional[Literal["web", "academic", "sec"]] | Omit = omit,
@@ -73,6 +74,9 @@ def create(
         Search the web and retrieve relevant web page contents.
 
         Args:
+          search_context_size: Controls how much search context is retrieved. Higher values return more content
+              per result.
+
           search_type: Search type — "web" for general web search, "people" for people search.
               max_results above 20 is only supported for people search.
 
@@ -98,6 +102,7 @@ def create(
                     "max_tokens_per_page": max_tokens_per_page,
                     "search_after_date_filter": search_after_date_filter,
                     "search_before_date_filter": search_before_date_filter,
+                    "search_context_size": search_context_size,
                     "search_domain_filter": search_domain_filter,
                     "search_language_filter": search_language_filter,
                     "search_mode": search_mode,
@@ -146,6 +151,7 @@ async def create(
         max_tokens_per_page: int | Omit = omit,
         search_after_date_filter: Optional[str] | Omit = omit,
         search_before_date_filter: Optional[str] | Omit = omit,
+        search_context_size: Optional[Literal["low", "medium", "high"]] | Omit = omit,
         search_domain_filter: Optional[SequenceNotStr[str]] | Omit = omit,
         search_language_filter: Optional[SequenceNotStr[str]] | Omit = omit,
         search_mode: Optional[Literal["web", "academic", "sec"]] | Omit = omit,
@@ -162,6 +168,9 @@ async def create(
         Search the web and retrieve relevant web page contents.
 
         Args:
+          search_context_size: Controls how much search context is retrieved. Higher values return more content
+              per result.
+
           search_type: Search type — "web" for general web search, "people" for people search.
               max_results above 20 is only supported for people search.
 
@@ -187,6 +196,7 @@ async def create(
                     "max_tokens_per_page": max_tokens_per_page,
                     "search_after_date_filter": search_after_date_filter,
                     "search_before_date_filter": search_before_date_filter,
+                    "search_context_size": search_context_size,
                     "search_domain_filter": search_domain_filter,
                     "search_language_filter": search_language_filter,
                     "search_mode": search_mode,