> ## 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

> SDK reference for the Responses API, available in Node.js and Python.

## 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"}}
    {
        "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],
        },
        "identity": {  # optional
            "display_name": Optional[str],
            "email": Optional[str],
            "id": str,  # required
            "metadata": List[Dict[str, Any]],
            "tags": List[str],
        },
        "input": Union[str, List[CreateRouterResponseInput2]],
        "instructions": 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],
        },
        "max_output_tokens": Optional[int],
        "max_tool_calls": Optional[int],
        "memory": {  # optional
            "entity_id": str,  # required
        },
        "metadata": Dict[str, str],
        "model": Optional[str],
        "parallel_tool_calls": Optional[bool],
        "plugins": {  # optional
            "entities": List[str],
            "id": Literal["pii_redaction"],  # required
            "language": Optional[Literal["en", "nl"]],
            "on_failure": Optional[Literal["block", "passthrough"]],
            "persist_redacted_to_traces": Optional[bool],
            "threshold": Optional[float],
        },
        "presence_penalty": Optional[float],
        "previous_response_id": Optional[str],
        "prompt_cache_key": Optional[str],
        "reasoning": {  # optional
            "effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh"]],
            "summary": Optional[Literal["concise", "detailed", "auto"]],
        },
        "retry": {  # optional
            "count": int,  # required
            "on_codes": List[int],  # required
        },
        "safety_identifier": Optional[str],
        "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],
            "verbosity": Optional[Literal["low", "medium", "high"]],
        },
        "thread": {  # optional
            "id": str,  # required
            "tags": List[str],
        },
        "tool_choice": Union[Shorthand, SpecificFunction],
        "tools": Union[ToolsFunction, OrqAiTool, OrqAiTool, OrqAiTool, OrqAiTool, OrqAiTool, OrqAiTool, ToolsMCPTool],
        "top_logprobs": Optional[int],
        "top_p": Optional[float],
        "variables": Dict[str, Any],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      cacheControl?: {
        ttl?: string;
        type: string;  // required
      };
      conversation?: {
        id: string;  // required
      };
      fallbacks?: {
        model: string;  // required
      };
      frequencyPenalty?: number;
      guardrails?: {
        executeOn: string;  // required
        id: string;  // required
        isGuardrail?: boolean;
        sampleRate?: number;
      };
      identity?: {
        displayName?: string;
        email?: string;
        id: string;  // required
        metadata?: Record<string, any>[];
        tags?: string[];
      };
      input?: string;
      instructions?: string;
      limits?: {
        maxCost?: number;
        maxDepth?: number;
        maxExecutionTime?: number;
        maxIterations?: number;
        toolTimeout?: number;
      };
      maxOutputTokens?: number;
      maxToolCalls?: number;
      memory?: {
        entityId: string;  // required
      };
      metadata?: Record<string, string>;
      model?: string;
      parallelToolCalls?: boolean;
      plugins?: {
        entities?: string[];
        id: string;  // required
        language?: string;
        onFailure?: string;
        persistRedactedToTraces?: boolean;
        threshold?: number;
      };
      presencePenalty?: number;
      previousResponseId?: string;
      promptCacheKey?: string;
      reasoning?: {
        effort?: string;
        summary?: string;
      };
      retry?: {
        count: number;  // required
        onCodes: number[];  // required
      };
      safetyIdentifier?: string;
      store?: boolean;
      stream?: boolean;
      streamOptions?: {
        includeObfuscation: boolean;  // required
      };
      temperature?: number;
      templateEngine?: string;
      text?: {
        format?: string;
        verbosity?: string;
      };
      thread?: {
        id: string;  // required
        tags?: string[];
      };
      toolChoice?: string;
      tools?: string;
      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_retention": Nullable[str],
        "reasoning": {
            "effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh"]],
            "summary": Optional[Literal["concise", "detailed", "auto"]],
        },
        "safety_identifier": Nullable[str],
        "service_tier": Literal["auto", "default", "flex", "priority"],
        "status": Literal["queued", "in_progress", "completed", "failed", "incomplete", "requires_action"],
        "store": bool,
        "temperature": float,
        "text": Any,
        "tool_choice": Any,
        "tools": List[Any],
        "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,
                "cached_tokens": int,
            },
            "output_cost": Optional[float],
            "output_tokens": int,
            "output_tokens_details": {
                "reasoning_tokens": int,
            },
            "total_cost": Optional[float],
            "total_tokens": int,
            "web_search_requests": Optional[int],
        },
        "user": Nullable[str],
        "variables": Dict[str, Any],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      background: boolean;
      completed_at: Nullable[number];
      conversation?: {
        id: string;
      };
      created_at: number;
      error: {
        code: string;
        message: string;
      };
      frequency_penalty: number;
      id: string;
      incomplete_details: {
        reason: string;
      };
      input: unknown[];
      instructions: Nullable[string];
      max_output_tokens: Nullable[number];
      max_tool_calls: Nullable[number];
      memory?: {
        entity_id: string;
      };
      metadata: Record<string, unknown>;
      model: string;
      object: string;
      output: unknown[];
      parallel_tool_calls: boolean;
      presence_penalty: number;
      previous_response_id: Nullable[string];
      prompt_cache_key: Nullable[string];
      prompt_cache_retention: Nullable[string];
      reasoning: {
        effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | undefined;
        summary?: "concise" | "detailed" | "auto" | undefined;
      };
      safety_identifier: Nullable[string];
      service_tier: "auto" | "default" | "flex" | "priority";
      status: "queued" | "in_progress" | "completed" | "failed" | "incomplete" | "requires_action";
      store: boolean;
      temperature: number;
      text: unknown;
      tool_choice: unknown;
      tools: unknown[];
      top_logprobs: number;
      top_p: number;
      truncation: "disabled" | "auto";
      usage: {
        input_cost?: number | undefined;
        input_tokens: number;
        input_tokens_details: {
          cache_creation_1h_tokens?: number | undefined;
          cache_creation_5m_tokens?: number | undefined;
          cache_creation_tokens: number;
          cached_tokens: number;
        };
        output_cost?: number | undefined;
        output_tokens: number;
        output_tokens_details: {
          reasoning_tokens: number;
        };
        total_cost?: number | undefined;
        total_tokens: number;
        web_search_requests?: number | undefined;
      };
      user: Nullable[string];
      variables?: Record<string, unknown>;
    }
    ```
  </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_retention": Nullable[str],
        "reasoning": {
            "effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh"]],
            "summary": Optional[Literal["concise", "detailed", "auto"]],
        },
        "safety_identifier": Nullable[str],
        "service_tier": Literal["auto", "default", "flex", "priority"],
        "status": Literal["queued", "in_progress", "completed", "failed", "incomplete", "requires_action"],
        "store": bool,
        "temperature": float,
        "text": Any,
        "tool_choice": Any,
        "tools": List[Any],
        "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,
                "cached_tokens": int,
            },
            "output_cost": Optional[float],
            "output_tokens": int,
            "output_tokens_details": {
                "reasoning_tokens": int,
            },
            "total_cost": Optional[float],
            "total_tokens": int,
            "web_search_requests": Optional[int],
        },
        "user": Nullable[str],
        "variables": Dict[str, Any],
    }
    ```

    ```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;
      promptCacheRetention: string;
      reasoning: {
        effort?: string;
        summary?: string;
      };
      safetyIdentifier: string;
      serviceTier: string;
      status: string;
      store: boolean;
      temperature: number;
      text: any;
      toolChoice: any;
      tools: any[];
      topLogprobs: number;
      topP: number;
      truncation: string;
      usage: {
        inputCost?: number;
        inputTokens: number;
        inputTokensDetails: {
          cacheCreation1hTokens?: number;
          cacheCreation5mTokens?: number;
          cacheCreationTokens: number;
          cachedTokens: number;
        };
        outputCost?: number;
        outputTokens: number;
        outputTokensDetails: {
          reasoningTokens: number;
        };
        totalCost?: number;
        totalTokens: number;
        webSearchRequests?: number;
      };
      user: string;
      variables?: Record<string, any>;
    }
    ```
  </CodeGroup>
</Expandable>