feat(api): search_context_size, background tasks, reasoning effort xhigh + responses.retrieve

API-2610: add search_context_size to Search API (low/medium/high, default low)
API-2621: add background tasks (background:true + GET /v1/responses/{id} polling)
  + add 'minimal' and 'xhigh' to reasoning.effort enum
  + add 'queued' and 'cancelled' to Status enum

Author: stainless-app[bot]

.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

api.md

@@ -54,10 +54,12 @@ Types:
 - <code><a href="./src/resources/responses.ts">ResponsesCreateParams</a></code>
 - <code><a href="./src/resources/responses.ts">ResponsesUsage</a></code>
 - <code><a href="./src/resources/responses.ts">ResponseCreateResponse</a></code>
+- <code><a href="./src/resources/responses.ts">ResponseRetrieveResponse</a></code>
 
 Methods:
 
 - <code title="post /v1/responses">client.responses.<a href="./src/resources/responses.ts">create</a>({ ...params }) -> ResponseCreateResponse</code>
+- <code title="get /v1/responses/{response_id}">client.responses.<a href="./src/resources/responses.ts">retrieve</a>(responseID) -> ResponseRetrieveResponse</code>
 
 # Embeddings
 

src/client.ts

@@ -35,6 +35,7 @@ import {
   ResponseCreateParamsNonStreaming,
   ResponseCreateParamsStreaming,
   ResponseCreateResponse,
+  ResponseRetrieveResponse,
   ResponseStreamChunk,
   Responses,
   ResponsesCreateParams,
@@ -799,6 +800,7 @@ export declare namespace Perplexity {
     type ResponsesCreateParams as ResponsesCreateParams,
     type ResponsesUsage as ResponsesUsage,
     type ResponseCreateResponse as ResponseCreateResponse,
+    type ResponseRetrieveResponse as ResponseRetrieveResponse,
     type ResponseCreateParams as ResponseCreateParams,
     type ResponseCreateParamsNonStreaming as ResponseCreateParamsNonStreaming,
     type ResponseCreateParamsStreaming as ResponseCreateParamsStreaming,

src/resources/index.ts

@@ -23,6 +23,7 @@ export {
   type ResponsesCreateParams,
   type ResponsesUsage,
   type ResponseCreateResponse,
+  type ResponseRetrieveResponse,
   type ResponseCreateParams,
   type ResponseCreateParamsNonStreaming,
   type ResponseCreateParamsStreaming,

src/resources/responses.ts

@@ -7,6 +7,7 @@ import { APIPromise } from '../core/api-promise';
 import { Stream } from '../core/streaming';
 import { RequestOptions } from '../internal/request-options';
 import { addOutputText } from '../lib/add-output-text';
+import { path } from '../internal/utils/path';
 
 export class Responses extends APIResource {
   /**
@@ -43,6 +44,13 @@ export class Responses extends APIResource {
 
     return promise as APIPromise<Stream<ResponseStreamChunk>>;
   }
+
+  /**
+   * Retrieve a response by its ID. Use this to poll the status of background tasks.
+   */
+  retrieve(responseID: string, options?: RequestOptions): APIPromise<ResponseRetrieveResponse> {
+    return this._client.get(path`/v1/responses/${responseID}`, options);
+  }
 }
 
 /**
@@ -97,7 +105,7 @@ export interface FunctionCallOutputItem {
   /**
    * Status of a response or output item
    */
-  status: 'completed' | 'failed' | 'in_progress' | 'requires_action';
+  status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';
 
   type: 'function_call';
 
@@ -227,7 +235,7 @@ export namespace OutputItem {
     /**
      * Status of a response or output item
      */
-    status: 'completed' | 'failed' | 'in_progress' | 'requires_action';
+    status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';
 
     type: 'message';
   }
@@ -346,7 +354,12 @@ export namespace ResponseStreamChunk {
       /**
        * Status of a response or output item
        */
-      status: 'completed' | 'failed' | 'in_progress' | 'requires_action';
+      status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';
+
+      /**
+       * Whether the response was created in background mode.
+       */
+      background?: boolean;
 
       error?: ResponsesAPI.ErrorInfo;
 
@@ -396,7 +409,12 @@ export namespace ResponseStreamChunk {
       /**
        * Status of a response or output item
        */
-      status: 'completed' | 'failed' | 'in_progress' | 'requires_action';
+      status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';
+
+      /**
+       * Whether the response was created in background mode.
+       */
+      background?: boolean;
 
       error?: ResponsesAPI.ErrorInfo;
 
@@ -445,7 +463,12 @@ export namespace ResponseStreamChunk {
       /**
        * Status of a response or output item
        */
-      status: 'completed' | 'failed' | 'in_progress' | 'requires_action';
+      status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';
+
+      /**
+       * Whether the response was created in background mode.
+       */
+      background?: boolean;
 
       error?: ResponsesAPI.ErrorInfo;
 
@@ -706,6 +729,13 @@ export interface ResponsesCreateParams {
    */
   input: string | Array<InputItem>;
 
+  /**
+   * 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.
+   */
+  background?: boolean | null;
+
   /**
    * System instructions for the model
    */
@@ -778,7 +808,7 @@ export namespace ResponsesCreateParams {
     /**
      * How much effort the model should spend on reasoning
      */
-    effort?: 'low' | 'medium' | 'high';
+    effort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
   }
 
   export interface WebSearchTool {
@@ -936,7 +966,44 @@ export interface ResponseCreateResponse {
   /**
    * Status of a response or output item
    */
-  status: 'completed' | 'failed' | 'in_progress' | 'requires_action';
+  status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';
+
+  /**
+   * Whether the response was created in background mode.
+   */
+  background?: boolean;
+
+  error?: ErrorInfo;
+
+  usage?: ResponsesUsage;
+}
+
+/**
+ * Non-streaming response returned when stream is false
+ */
+export interface ResponseRetrieveResponse {
+  id: string;
+
+  created_at: number;
+
+  model: string;
+
+  /**
+   * Object type in API responses
+   */
+  object: 'response';
+
+  output: Array<OutputItem>;
+
+  /**
+   * Status of a response or output item
+   */
+  status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';
+
+  /**
+   * Whether the response was created in background mode.
+   */
+  background?: boolean;
 
   error?: ErrorInfo;
 
@@ -957,6 +1024,13 @@ export interface ResponseCreateParamsBase {
    */
   input: string | Array<InputItem>;
 
+  /**
+   * 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.
+   */
+  background?: boolean | null;
+
   /**
    * System instructions for the model
    */
@@ -1029,7 +1103,7 @@ export namespace ResponseCreateParams {
     /**
      * How much effort the model should spend on reasoning
      */
-    effort?: 'low' | 'medium' | 'high';
+    effort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
   }
 
   export interface WebSearchTool {
@@ -1149,6 +1223,7 @@ export declare namespace Responses {
     type ResponsesCreateParams as ResponsesCreateParams,
     type ResponsesUsage as ResponsesUsage,
     type ResponseCreateResponse as ResponseCreateResponse,
+    type ResponseRetrieveResponse as ResponseRetrieveResponse,
     type ResponseCreateParams as ResponseCreateParams,
     type ResponseCreateParamsNonStreaming as ResponseCreateParamsNonStreaming,
     type ResponseCreateParamsStreaming as ResponseCreateParamsStreaming,

src/resources/search.ts

@@ -56,6 +56,12 @@ export interface SearchCreateParams {
 
   search_before_date_filter?: string | null;
 
+  /**
+   * Controls how much search context is retrieved. Higher values return more content
+   * per result.
+   */
+  search_context_size?: 'low' | 'medium' | 'high' | null;
+
   search_domain_filter?: Array<string> | null;
 
   search_language_filter?: Array<string> | null;

tests/api-resources/responses.test.ts

@@ -24,14 +24,15 @@ describe('resource responses', () => {
   test.skip('create: required and optional params', async () => {
     const response = await client.responses.create({
       input: 'string',
+      background: true,
       instructions: 'instructions',
       language_preference: 'language_preference',
       max_output_tokens: 1,
       max_steps: 1,
       model: 'model',
       models: ['string'],
       preset: 'preset',
-      reasoning: { effort: 'low' },
+      reasoning: { effort: 'minimal' },
       response_format: {
         type: 'json_schema',
         json_schema: {
@@ -66,4 +67,16 @@ describe('resource responses', () => {
       ],
     });
   });
+
+  // Mock server tests are disabled
+  test.skip('retrieve', async () => {
+    const responsePromise = client.responses.retrieve('response_id');
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
 });

tests/api-resources/search.test.ts

@@ -33,6 +33,7 @@ describe('resource search', () => {
       max_tokens_per_page: 0,
       search_after_date_filter: 'search_after_date_filter',
       search_before_date_filter: 'search_before_date_filter',
+      search_context_size: 'low',
       search_domain_filter: ['string'],
       search_language_filter: ['string'],
       search_mode: 'web',