> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses SDK Reference

> Create and retrieve model responses through the Orq AI Gateway with the Node.js and Python SDKs, including streaming via server-sent events.

## Responses

### Create a Response

Creates a model response for the given input. Returns a response object or a stream of server-sent events.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.responses.create()

      with res as event_stream:
          for event in event_stream:
              # handle event
              print(event, flush=True)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.responses.create({});

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "background": Optional[bool],
        "cache": {  # optional
            "ttl": Optional[int],
            "type": str,  # required
        },
        "cache_control": {  # optional
            "ttl": Optional[Literal["5m", "1h"]],
            "type": Literal["ephemeral"],  # required
        },
        "conversation": {  # optional
            "id": str,  # required
        },
        "fallbacks": [{  # optional
            "model": str,  # required
        }],
        "frequency_penalty": Optional[float],
        "guardrails": [{  # optional
            "execute_on": Literal["input", "output", "both"],  # required
            "id": str,  # required
            "is_guardrail": Optional[bool],
            "sample_rate": Optional[float],
            "timeout": Optional[int],
        }],
        "identity": {  # optional
            "display_name": Optional[str],
            "email": Optional[str],
            "id": str,  # required
            "metadata": List[Dict[str, Any]],  # optional
            "tags": List[str],  # optional
        },
        "input": Union[str, List[CreateRouterResponseInput2]],  # optional
        "instructions": Optional[str],
        "integration_id": Optional[str],
        "limits": {  # optional
            "max_cost": Optional[float],
            "max_depth": Optional[int],
            "max_execution_time": Optional[int],
            "max_iterations": Optional[int],
            "tool_timeout": Optional[int],
        },
        "load_balancer": {  # optional
            "models": [{  # required
                "model": str,  # required
                "weight": float,  # required
            }],
            "type": str,  # required
        },
        "max_output_tokens": Optional[int],
        "max_tool_calls": Optional[int],
        "memory": {  # optional
            "entity_id": str,  # required
        },
        "metadata": Dict[str, str],  # optional
        "model": Optional[str],
        "parallel_tool_calls": Optional[bool],
        "plugins": [{  # optional
            "entities": List[str],  # optional
            "entity_thresholds": Dict[str, float],  # optional
            "id": Literal["pii_redaction", "response_healing", "trace_scrubbing"],  # required
            "language": Optional[str],
            "mask": List[Literal["all", "system", "input", "output", "metadata", "variables"]],  # optional
            "on_failure": Optional[Literal["block", "passthrough"]],
            "regions": List[str],  # optional
            "threshold": Optional[float],
        }],
        "presence_penalty": Optional[float],
        "previous_response_id": Optional[str],
        "prompt_cache_key": Optional[str],
        "prompt_cache_options": {  # optional
            "mode": Optional[Literal["implicit", "explicit"]],
            "ttl": Optional[Literal["30m"]],
        },
        "reasoning": {  # optional
            "effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
            "summary": Optional[Literal["concise", "detailed", "auto"]],
        },
        "retry": {  # optional
            "count": int,  # required
            "on_codes": List[int],  # required
        },
        "safety_identifier": Optional[str],
        "security": {  # optional
            "mask": List[str],  # optional
        },
        "service_tier": Optional[Literal["auto", "default", "flex", "fast", "scale", "priority"]],
        "stop_sequences": List[str],  # optional
        "store": Optional[bool],
        "stream": Optional[bool],
        "stream_options": {  # optional
            "include_obfuscation": bool,  # required
        },
        "temperature": Optional[float],
        "template_engine": Optional[Literal["text", "jinja", "mustache"]],
        "text": {  # optional
            "format_": Union[PlainText, FormatJSONSchema],  # optional
            "verbosity": Optional[Literal["low", "medium", "high"]],
        },
        "thread": {  # optional
            "id": str,  # required
            "tags": List[str],  # optional
        },
        "timeout": {  # optional
            "call_timeout": int,  # required
        },
        "tool_choice": Union[Shorthand, SpecificFunction],  # optional
        "tools": List[Union[ToolsFunction, Custom, OrqAdvisorTool, OrqSidekickTool, OrqAiTool, ToolsMCPTool]],  # optional
        "top_k": Optional[int],
        "top_logprobs": Optional[int],
        "top_p": Optional[float],
        "variables": Dict[str, Any],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      background?: boolean;
      cache?: {
        ttl?: number;
        type: string;  // required
      };
      cacheControl?: {
        ttl?: "5m" | "1h";
        type: "ephemeral";  // required
      };
      conversation?: {
        id: string;  // required
      };
      fallbacks?: {
        model: string;  // required
      }[];
      frequencyPenalty?: number;
      guardrails?: {
        executeOn: "input" | "output" | "both";  // required
        id: string;  // required
        isGuardrail?: boolean;
        sampleRate?: number;
        timeout?: number;
      }[];
      identity?: {
        displayName?: string;
        email?: string;
        id: string;  // required
        metadata?: Record<string, any>[];
        tags?: string[];
      };
      input?: string | CreateRouterResponseInput2[];
      instructions?: string;
      integrationId?: string;
      limits?: {
        maxCost?: number;
        maxDepth?: number;
        maxExecutionTime?: number;
        maxIterations?: number;
        toolTimeout?: number;
      };
      loadBalancer?: {
        models: {  // required
          model: string;  // required
          weight: number;  // required
        }[];
        type: string;  // required
      };
      maxOutputTokens?: number;
      maxToolCalls?: number;
      memory?: {
        entityId: string;  // required
      };
      metadata?: Record<string, string>;
      model?: string;
      parallelToolCalls?: boolean;
      plugins?: {
        entities?: string[];
        entityThresholds?: Record<string, number>;
        id: "pii_redaction" | "response_healing" | "trace_scrubbing";  // required
        language?: string;
        mask?: ("all" | "system" | "input" | "output" | "metadata" | "variables")[];
        onFailure?: "block" | "passthrough";
        regions?: string[];
        threshold?: number;
      }[];
      presencePenalty?: number;
      previousResponseId?: string;
      promptCacheKey?: string;
      promptCacheOptions?: {
        mode?: "implicit" | "explicit";
        ttl?: "30m";
      };
      reasoning?: {
        effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
        summary?: "concise" | "detailed" | "auto";
      };
      retry?: {
        count: number;  // required
        onCodes: number[];  // required
      };
      safetyIdentifier?: string;
      security?: {
        mask?: string[];
      };
      serviceTier?: "auto" | "default" | "flex" | "fast" | "scale" | "priority";
      stopSequences?: string[];
      store?: boolean;
      stream?: boolean;
      streamOptions?: {
        includeObfuscation: boolean;  // required
      };
      temperature?: number;
      templateEngine?: "text" | "jinja" | "mustache";
      text?: {
        format?: PlainText | FormatJSONSchema;
        verbosity?: "low" | "medium" | "high";
      };
      thread?: {
        id: string;  // required
        tags?: string[];
      };
      timeout?: {
        callTimeout: number;  // required
      };
      toolChoice?: Shorthand | SpecificFunction;
      tools?: (ToolsFunction | Custom | OrqAdvisorTool | OrqSidekickTool | OrqAiTool | MCPTool)[];
      topK?: number;
      topLogprobs?: number;
      topP?: number;
      variables?: Record<string, any>;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "background": bool,
        "completed_at": Nullable[int],
        "conversation": {  # optional
            "id": str,
        },
        "created_at": int,
        "error": {
            "code": str,
            "message": str,
        },
        "frequency_penalty": float,
        "id": str,
        "incomplete_details": {
            "reason": str,
        },
        "input": List[Any],
        "instructions": Nullable[str],
        "max_output_tokens": Nullable[int],
        "max_tool_calls": Nullable[int],
        "memory": {  # optional
            "entity_id": str,
        },
        "metadata": Dict[str, str],
        "model": str,
        "object": str,
        "output": List[Any],
        "parallel_tool_calls": bool,
        "presence_penalty": float,
        "previous_response_id": Nullable[str],
        "prompt_cache_key": Nullable[str],
        "prompt_cache_options": {
            "mode": Optional[Literal["implicit", "explicit"]],
            "ttl": Optional[Literal["30m"]],
        },
        "prompt_cache_retention": Nullable[str],
        "reasoning": {
            "effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
            "summary": Optional[Literal["concise", "detailed", "auto"]],
        },
        "safety_identifier": Nullable[str],
        "service_tier": Literal["auto", "default", "flex", "fast", "scale", "priority"],
        "status": Literal["queued", "in_progress", "completed", "failed", "incomplete"],
        "store": bool,
        "telemetry": {  # optional
            "span_id": str,
            "trace_id": str,
        },
        "temperature": float,
        "text": Any,
        "tool_choice": Any,
        "tools": List[Any],
        "top_k": Optional[int],
        "top_logprobs": int,
        "top_p": float,
        "truncation": Literal["disabled", "auto"],
        "usage": {
            "input_cost": Optional[float],
            "input_tokens": int,
            "input_tokens_details": {
                "cache_creation_1h_tokens": Optional[int],
                "cache_creation_5m_tokens": Optional[int],
                "cache_creation_tokens": int,
                "cache_write_tokens": int,
                "cached_tokens": int,
            },
            "output_cost": Optional[float],
            "output_tokens": int,
            "output_tokens_details": {
                "reasoning_tokens": int,
            },
            "server_tool_use": {  # optional
                "advisor_requests": Optional[int],
                "code_interpreter_sessions": Optional[int],
                "datetime_requests": Optional[int],
                "fusion_requests": Optional[int],
                "image_generation_calls": Optional[int],
                "search_models_requests": Optional[int],
                "shell_commands": Optional[int],
                "subagent_requests": Optional[int],
                "web_fetch_requests": Optional[int],
                "web_search_requests": Optional[int],
            },
            "total_cost": Optional[float],
            "total_tokens": int,
            "web_search_requests": Optional[int],
        },
        "user": Nullable[str],
        "variables": Dict[str, Any],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      background: boolean;
      completedAt: number;
      conversation?: {
        id: string;
      };
      createdAt: number;
      error: {
        code: string;
        message: string;
      };
      frequencyPenalty: number;
      id: string;
      incompleteDetails: {
        reason: string;
      };
      input: any[];
      instructions: string;
      maxOutputTokens: number;
      maxToolCalls: number;
      memory?: {
        entityId: string;
      };
      metadata: Record<string, string>;
      model: string;
      object: string;
      output: any[];
      parallelToolCalls: boolean;
      presencePenalty: number;
      previousResponseId: string;
      promptCacheKey: string;
      promptCacheOptions: {
        mode?: "implicit" | "explicit";
        ttl?: "30m";
      };
      promptCacheRetention: string;
      reasoning: {
        effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
        summary?: "concise" | "detailed" | "auto";
      };
      safetyIdentifier: string;
      serviceTier: "auto" | "default" | "flex" | "fast" | "scale" | "priority";
      status: "queued" | "in_progress" | "completed" | "failed" | "incomplete";
      store: boolean;
      telemetry?: {
        spanId: string;
        traceId: string;
      };
      temperature: number;
      text: any;
      toolChoice: any;
      tools: any[];
      topK?: number;
      topLogprobs: number;
      topP: number;
      truncation: "disabled" | "auto";
      usage: {
        inputCost?: number;
        inputTokens: number;
        inputTokensDetails: {
          cacheCreation1hTokens?: number;
          cacheCreation5mTokens?: number;
          cacheCreationTokens: number;
          cacheWriteTokens: number;
          cachedTokens: number;
        };
        outputCost?: number;
        outputTokens: number;
        outputTokensDetails: {
          reasoningTokens: number;
        };
        serverToolUse?: {
          advisorRequests?: number;
          codeInterpreterSessions?: number;
          datetimeRequests?: number;
          fusionRequests?: number;
          imageGenerationCalls?: number;
          searchModelsRequests?: number;
          shellCommands?: number;
          subagentRequests?: number;
          webFetchRequests?: number;
          webSearchRequests?: number;
        };
        totalCost?: number;
        totalTokens: number;
        webSearchRequests?: number;
      };
      user: string;
      variables?: Record<string, any>;
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Response

Retrieves a previously created response by its ID.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.responses.get(response_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.responses.get({
      responseId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "response_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      responseId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "background": bool,
        "completed_at": Nullable[int],
        "conversation": {  # optional
            "id": str,
        },
        "created_at": int,
        "error": {
            "code": str,
            "message": str,
        },
        "frequency_penalty": float,
        "id": str,
        "incomplete_details": {
            "reason": str,
        },
        "input": List[Any],
        "instructions": Nullable[str],
        "max_output_tokens": Nullable[int],
        "max_tool_calls": Nullable[int],
        "memory": {  # optional
            "entity_id": str,
        },
        "metadata": Dict[str, str],
        "model": str,
        "object": str,
        "output": List[Any],
        "parallel_tool_calls": bool,
        "presence_penalty": float,
        "previous_response_id": Nullable[str],
        "prompt_cache_key": Nullable[str],
        "prompt_cache_options": {
            "mode": Optional[Literal["implicit", "explicit"]],
            "ttl": Optional[Literal["30m"]],
        },
        "prompt_cache_retention": Nullable[str],
        "reasoning": {
            "effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
            "summary": Optional[Literal["concise", "detailed", "auto"]],
        },
        "safety_identifier": Nullable[str],
        "service_tier": Literal["auto", "default", "flex", "fast", "scale", "priority"],
        "status": Literal["queued", "in_progress", "completed", "failed", "incomplete"],
        "store": bool,
        "telemetry": {  # optional
            "span_id": str,
            "trace_id": str,
        },
        "temperature": float,
        "text": Any,
        "tool_choice": Any,
        "tools": List[Any],
        "top_k": Optional[int],
        "top_logprobs": int,
        "top_p": float,
        "truncation": Literal["disabled", "auto"],
        "usage": {
            "input_cost": Optional[float],
            "input_tokens": int,
            "input_tokens_details": {
                "cache_creation_1h_tokens": Optional[int],
                "cache_creation_5m_tokens": Optional[int],
                "cache_creation_tokens": int,
                "cache_write_tokens": int,
                "cached_tokens": int,
            },
            "output_cost": Optional[float],
            "output_tokens": int,
            "output_tokens_details": {
                "reasoning_tokens": int,
            },
            "server_tool_use": {  # optional
                "advisor_requests": Optional[int],
                "code_interpreter_sessions": Optional[int],
                "datetime_requests": Optional[int],
                "fusion_requests": Optional[int],
                "image_generation_calls": Optional[int],
                "search_models_requests": Optional[int],
                "shell_commands": Optional[int],
                "subagent_requests": Optional[int],
                "web_fetch_requests": Optional[int],
                "web_search_requests": Optional[int],
            },
            "total_cost": Optional[float],
            "total_tokens": int,
            "web_search_requests": Optional[int],
        },
        "user": Nullable[str],
        "variables": Dict[str, Any],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      background: boolean;
      completedAt: number;
      conversation?: {
        id: string;
      };
      createdAt: number;
      error: {
        code: string;
        message: string;
      };
      frequencyPenalty: number;
      id: string;
      incompleteDetails: {
        reason: string;
      };
      input: any[];
      instructions: string;
      maxOutputTokens: number;
      maxToolCalls: number;
      memory?: {
        entityId: string;
      };
      metadata: Record<string, string>;
      model: string;
      object: string;
      output: any[];
      parallelToolCalls: boolean;
      presencePenalty: number;
      previousResponseId: string;
      promptCacheKey: string;
      promptCacheOptions: {
        mode?: "implicit" | "explicit";
        ttl?: "30m";
      };
      promptCacheRetention: string;
      reasoning: {
        effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
        summary?: "concise" | "detailed" | "auto";
      };
      safetyIdentifier: string;
      serviceTier: "auto" | "default" | "flex" | "fast" | "scale" | "priority";
      status: "queued" | "in_progress" | "completed" | "failed" | "incomplete";
      store: boolean;
      telemetry?: {
        spanId: string;
        traceId: string;
      };
      temperature: number;
      text: any;
      toolChoice: any;
      tools: any[];
      topK?: number;
      topLogprobs: number;
      topP: number;
      truncation: "disabled" | "auto";
      usage: {
        inputCost?: number;
        inputTokens: number;
        inputTokensDetails: {
          cacheCreation1hTokens?: number;
          cacheCreation5mTokens?: number;
          cacheCreationTokens: number;
          cacheWriteTokens: number;
          cachedTokens: number;
        };
        outputCost?: number;
        outputTokens: number;
        outputTokensDetails: {
          reasoningTokens: number;
        };
        serverToolUse?: {
          advisorRequests?: number;
          codeInterpreterSessions?: number;
          datetimeRequests?: number;
          fusionRequests?: number;
          imageGenerationCalls?: number;
          searchModelsRequests?: number;
          shellCommands?: number;
          subagentRequests?: number;
          webFetchRequests?: number;
          webSearchRequests?: number;
        };
        totalCost?: number;
        totalTokens: number;
        webSearchRequests?: number;
      };
      user: string;
      variables?: Record<string, any>;
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.