---
title: "Beta.Responses"
description: "beta.responses endpoints"
---

## Overview

beta.responses endpoints

### Available Operations

* [send](#send) - Create a response

## send

Creates a streaming or non-streaming response using OpenResponses API format

### Example Usage: guardrail-blocked

```python
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.beta.responses.send(service_tier="auto", stream=False)

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

```
### Example Usage: insufficient-permissions

```python
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.beta.responses.send(service_tier="auto", stream=False)

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

```

### Parameters

| Parameter                                                                                                                                                                                                                                                                                                                                                                                                            | Type                                                                                                                                                                                                                                                                                                                                                                                                                 | Required                                                                                                                                                                                                                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                          | Example                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `http_referer`                                                                                                                                                                                                                                                                                                                                                                                                       | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | The app identifier should be your app's URL and is used as the primary identifier for rankings.<br/>This is used to track API usage per application.<br/>                                                                                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `x_open_router_title`                                                                                                                                                                                                                                                                                                                                                                                                | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | The app display name allows you to customize how your app appears in OpenRouter's dashboard.<br/>                                                                                                                                                                                                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `x_open_router_categories`                                                                                                                                                                                                                                                                                                                                                                                           | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.<br/>                                                                                                                                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `x_open_router_metadata`                                                                                                                                                                                                                                                                                                                                                                                             | [Optional[components.MetadataLevel]](../../components/metadatalevel.mdx)                                                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Opt-in to surface routing metadata on the response under `openrouter_metadata`. Defaults to `disabled`. The legacy header `X-OpenRouter-Experimental-Metadata` is also accepted for backward compatibility.                                                                                                                                                                                                          | enabled                                                                                                                                                                                                                                                                                                                                                                                                              |
| `background`                                                                                                                                                                                                                                                                                                                                                                                                         | *OptionalNullable[bool]*                                                                                                                                                                                                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `cache_control`                                                                                                                                                                                                                                                                                                                                                                                                      | [Optional[components.AnthropicCacheControlDirective]](../../components/anthropiccachecontroldirective.mdx)                                                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Enable automatic prompt caching. When set at the top level, the system automatically applies cache breakpoints to the last cacheable block in the request. When set on an individual content block, it marks an explicit cache breakpoint; block-level markers also work on OpenAI models that support explicit prompt caching — OpenRouter converts them to the provider's native format.                           | \{<br/>"type": "ephemeral"<br/>}                                                                                                                                                                                                                                                                                                                                                                                      |
| `debug`                                                                                                                                                                                                                                                                                                                                                                                                              | [Optional[components.ChatDebugOptions]](../../components/chatdebugoptions.mdx)                                                                                                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Debug options for inspecting request transformations (streaming only)                                                                                                                                                                                                                                                                                                                                                | \{<br/>"echo_upstream_body": true<br/>}                                                                                                                                                                                                                                                                                                                                                                               |
| `frequency_penalty`                                                                                                                                                                                                                                                                                                                                                                                                  | *OptionalNullable[float]*                                                                                                                                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `image_config`                                                                                                                                                                                                                                                                                                                                                                                                       | Dict[str, [components.ImageConfig](../../components/imageconfig.mdx)]                                                                                                                                                                                                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Provider-specific image configuration options. Keys and values vary by model/provider. See https://openrouter.ai/docs/guides/overview/multimodal/image-generation for more details.                                                                                                                                                                                                                                  | \{<br/>"aspect_ratio": "16:9",<br/>"quality": "high"<br/>}                                                                                                                                                                                                                                                                                                                                                            |
| `include`                                                                                                                                                                                                                                                                                                                                                                                                            | List[[components.ResponseIncludesEnum](../../components/responseincludesenum.mdx)]                                                                                                                                                                                                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `input`                                                                                                                                                                                                                                                                                                                                                                                                              | [Optional[components.InputsUnion]](../../components/inputsunion.mdx)                                                                                                                                                                                                                                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Input for a response request - can be a string or array of items                                                                                                                                                                                                                                                                                                                                                     | [<br/>\{<br/>"content": "What is the weather today?",<br/>"role": "user"<br/>}<br/>]                                                                                                                                                                                                                                                                                                                                  |
| `instructions`                                                                                                                                                                                                                                                                                                                                                                                                       | *OptionalNullable[str]*                                                                                                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `max_output_tokens`                                                                                                                                                                                                                                                                                                                                                                                                  | *OptionalNullable[int]*                                                                                                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `max_tool_calls`                                                                                                                                                                                                                                                                                                                                                                                                     | *OptionalNullable[int]*                                                                                                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `metadata`                                                                                                                                                                                                                                                                                                                                                                                                           | Dict[str, *str*]                                                                                                                                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Metadata key-value pairs for the request. Keys must be ≤64 characters and cannot contain brackets. Values must be ≤512 characters. Maximum 16 pairs allowed.                                                                                                                                                                                                                                                         | \{<br/>"session_id": "abc-def-ghi",<br/>"user_id": "123"<br/>}                                                                                                                                                                                                                                                                                                                                                        |
| `modalities`                                                                                                                                                                                                                                                                                                                                                                                                         | List[[components.OutputModalityEnum](../../components/outputmodalityenum.mdx)]                                                                                                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Output modalities for the response. Supported values are "text" and "image".                                                                                                                                                                                                                                                                                                                                         | [<br/>"text",<br/>"image"<br/>]                                                                                                                                                                                                                                                                                                                                                                                      |
| `model`                                                                                                                                                                                                                                                                                                                                                                                                              | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `models`                                                                                                                                                                                                                                                                                                                                                                                                             | List[*str*]                                                                                                                                                                                                                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `parallel_tool_calls`                                                                                                                                                                                                                                                                                                                                                                                                | *OptionalNullable[bool]*                                                                                                                                                                                                                                                                                                                                                                                             | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `plugins`                                                                                                                                                                                                                                                                                                                                                                                                            | List[[components.ResponsesRequestPlugin](../../components/responsesrequestplugin.mdx)]                                                                                                                                                                                                                                                                                                                                | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Plugins you want to enable for this request, including their settings.                                                                                                                                                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `presence_penalty`                                                                                                                                                                                                                                                                                                                                                                                                   | *OptionalNullable[float]*                                                                                                                                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `previous_response_id`                                                                                                                                                                                                                                                                                                                                                                                               | *OptionalNullable[str]*                                                                                                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `prompt`                                                                                                                                                                                                                                                                                                                                                                                                             | [OptionalNullable[components.StoredPromptTemplate]](../../components/storedprompttemplate.mdx)                                                                                                                                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  | \{<br/>"id": "prompt-abc123",<br/>"variables": \{<br/>"name": "John"<br/>}<br/>}                                                                                                                                                                                                                                                                                                                                       |
| `prompt_cache_key`                                                                                                                                                                                                                                                                                                                                                                                                   | *OptionalNullable[str]*                                                                                                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `prompt_cache_options`                                                                                                                                                                                                                                                                                                                                                                                               | [OptionalNullable[components.PromptCacheOptions]](../../components/promptcacheoptions.mdx)                                                                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Request-level prompt-cache controls. `mode: "explicit"` disables OpenAI-managed breakpoints so only blocks marked with `prompt_cache_breakpoint` are cached. Only supported by OpenAI GPT-5.6 and newer.                                                                                                                                                                                                             | \{<br/>"mode": "explicit",<br/>"ttl": "30m"<br/>}                                                                                                                                                                                                                                                                                                                                                                     |
| `provider`                                                                                                                                                                                                                                                                                                                                                                                                           | [OptionalNullable[components.ProviderPreferences]](../../components/providerpreferences.mdx)                                                                                                                                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | When multiple model providers are available, optionally indicate your routing preference.                                                                                                                                                                                                                                                                                                                            | \{<br/>"allow_fallbacks": true<br/>}                                                                                                                                                                                                                                                                                                                                                                                  |
| `reasoning`                                                                                                                                                                                                                                                                                                                                                                                                          | [OptionalNullable[components.ReasoningConfig]](../../components/reasoningconfig.mdx)                                                                                                                                                                                                                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Configuration for reasoning mode in the response                                                                                                                                                                                                                                                                                                                                                                     | \{<br/>"enabled": true,<br/>"summary": "auto"<br/>}                                                                                                                                                                                                                                                                                                                                                                   |
| `safety_identifier`                                                                                                                                                                                                                                                                                                                                                                                                  | *OptionalNullable[str]*                                                                                                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `service_tier`                                                                                                                                                                                                                                                                                                                                                                                                       | [OptionalNullable[components.ResponsesRequestServiceTier]](../../components/responsesrequestservicetier.mdx)                                                                                                                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `session_id`                                                                                                                                                                                                                                                                                                                                                                                                         | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | A unique identifier for grouping related requests (e.g., a conversation or agent workflow). When provided, OpenRouter uses it as the sticky routing key, routing all requests in the session to the same provider to maximize prompt cache hits. Also used for observability grouping. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters. |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `stop_server_tools_when`                                                                                                                                                                                                                                                                                                                                                                                             | List[[components.StopServerToolsWhenCondition](../../components/stopservertoolswhencondition.mdx)]                                                                                                                                                                                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Stop conditions for the server-tool agent loop. Any condition firing halts the loop (OR logic). When set, this overrides `max_tool_calls`.                                                                                                                                                                                                                                                                           | [<br/>\{<br/>"step_count": 5,<br/>"type": "step_count_is"<br/>},<br/>\{<br/>"max_cost_in_dollars": 0.5,<br/>"type": "max_cost"<br/>}<br/>]                                                                                                                                                                                                                                                                             |
| `stream`                                                                                                                                                                                                                                                                                                                                                                                                             | *Optional[bool]*                                                                                                                                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `temperature`                                                                                                                                                                                                                                                                                                                                                                                                        | *OptionalNullable[float]*                                                                                                                                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `text`                                                                                                                                                                                                                                                                                                                                                                                                               | [Optional[components.TextExtendedConfig]](../../components/textextendedconfig.mdx)                                                                                                                                                                                                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Text output configuration including format and verbosity                                                                                                                                                                                                                                                                                                                                                             | \{<br/>"format": \{<br/>"type": "text"<br/>}<br/>}                                                                                                                                                                                                                                                                                                                                                                     |
| `tool_choice`                                                                                                                                                                                                                                                                                                                                                                                                        | [Optional[components.OpenAIResponsesToolChoiceUnion]](../../components/openairesponsestoolchoiceunion.mdx)                                                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  | auto                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `tools`                                                                                                                                                                                                                                                                                                                                                                                                              | List[[components.ResponsesRequestToolUnion](../../components/responsesrequesttoolunion.mdx)]                                                                                                                                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `top_k`                                                                                                                                                                                                                                                                                                                                                                                                              | *Optional[int]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `top_logprobs`                                                                                                                                                                                                                                                                                                                                                                                                       | *OptionalNullable[int]*                                                                                                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `top_p`                                                                                                                                                                                                                                                                                                                                                                                                              | *OptionalNullable[float]*                                                                                                                                                                                                                                                                                                                                                                                            | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `trace`                                                                                                                                                                                                                                                                                                                                                                                                              | [Optional[components.TraceConfig]](../../components/traceconfig.mdx)                                                                                                                                                                                                                                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations.                                                                                                                                                                             | \{<br/>"trace_id": "trace-abc123",<br/>"trace_name": "my-app-trace"<br/>}                                                                                                                                                                                                                                                                                                                                             |
| `truncation`                                                                                                                                                                                                                                                                                                                                                                                                         | [OptionalNullable[components.OpenAIResponsesTruncation]](../../components/openairesponsestruncation.mdx)                                                                                                                                                                                                                                                                                                              | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | N/A                                                                                                                                                                                                                                                                                                                                                                                                                  | auto                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `user`                                                                                                                                                                                                                                                                                                                                                                                                               | *Optional[str]*                                                                                                                                                                                                                                                                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | A unique identifier representing your end-user, which helps distinguish between different users of your app. This allows your app to identify specific users in case of abuse reports, preventing your entire app from being affected by the actions of individual users. Maximum of 256 characters.                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `retries`                                                                                                                                                                                                                                                                                                                                                                                                            | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx)                                                                                                                                                                                                                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                                                                                                                                                                                                                   | Configuration to override the default retry behavior of the client.                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                      |

### Response

**[operations.CreateResponsesResponse](../../operations/createresponsesresponse.mdx)**

### Errors

| Error Type                              | Status Code                             | Content Type                            |
| --------------------------------------- | --------------------------------------- | --------------------------------------- |
| errors.BadRequestResponseError          | 400                                     | application/json                        |
| errors.UnauthorizedResponseError        | 401                                     | application/json                        |
| errors.PaymentRequiredResponseError     | 402                                     | application/json                        |
| errors.ForbiddenResponseError           | 403                                     | application/json                        |
| errors.NotFoundResponseError            | 404                                     | application/json                        |
| errors.RequestTimeoutResponseError      | 408                                     | application/json                        |
| errors.PayloadTooLargeResponseError     | 413                                     | application/json                        |
| errors.UnprocessableEntityResponseError | 422                                     | application/json                        |
| errors.TooManyRequestsResponseError     | 429                                     | application/json                        |
| errors.InternalServerResponseError      | 500                                     | application/json                        |
| errors.BadGatewayResponseError          | 502                                     | application/json                        |
| errors.ServiceUnavailableResponseError  | 503                                     | application/json                        |
| errors.EdgeNetworkTimeoutResponseError  | 524                                     | application/json                        |
| errors.ProviderOverloadedResponseError  | 529                                     | application/json                        |
| errors.OpenRouterDefaultError           | 4XX, 5XX                                | \*/\*                                   |