Responses API Beta Web Search | Real-time Information Retrieval | OpenRouter

Beta API

This API is in beta stage and may have breaking changes.

The Responses API Beta supports web search integration, allowing models to access real-time information from the internet and provide responses with proper citations and annotations.

Web Search Plugin

Enable web search using the plugins parameter:

Plugin Configuration

Configure web search behavior:

Parameter	Type	Description
`id`	string	Required. Must be “web”
`max_results`	integer	Maximum search results to retrieve (1-10)

Structured Message with Web Search

Use structured messages for more complex queries:

Online Model Variants

Some models have built-in web search capabilities using the :online variant:

Response with Annotations

Web search responses include citation annotations:

1 {
2   "id": "resp_1234567890",
3   "object": "response",
4   "created_at": 1234567890,
5   "model": "openai/o4-mini",
6   "output": [
7     {
8       "type": "message",
9       "id": "msg_abc123",
10       "status": "completed",
11       "role": "assistant",
12       "content": [
13         {
14           "type": "output_text",
15           "text": "OpenRouter is a unified API for accessing multiple Large Language Model providers through a single interface. It allows developers to access 100+ AI models from providers like OpenAI, Anthropic, Google, and others with intelligent routing and automatic failover.",
16           "annotations": [
17             {
18               "type": "url_citation",
19               "url": "https://openrouter.ai/docs",
20               "start_index": 0,
21               "end_index": 85
22             },
23             {
24               "type": "url_citation",
25               "url": "https://openrouter.ai/models",
26               "start_index": 120,
27               "end_index": 180
28             }
29           ]
30         }
31       ]
32     }
33   ],
34   "usage": {
35     "input_tokens": 15,
36     "output_tokens": 95,
37     "total_tokens": 110
38   },
39   "status": "completed"
40 }

Annotation Types

Web search responses can include different annotation types:

URL Citation

1 {
2   "type": "url_citation",
3   "url": "https://example.com/article",
4   "start_index": 0,
5   "end_index": 50
6 }

Complex Search Queries

Handle multi-part search queries:

Web Search in Conversation

Include web search in multi-turn conversations:

Streaming Web Search

Monitor web search progress with streaming:

Annotation Processing

Extract and process citation information:

Best Practices

Limit results: Use appropriate max_results to balance quality and speed
Handle annotations: Process citation annotations for proper attribution
Query specificity: Make search queries specific for better results
Error handling: Handle cases where web search might fail
Rate limits: Be mindful of search rate limits

Next Steps

Learn about Tool Calling integration
Explore Reasoning capabilities
Review Basic Usage fundamentals

1	{
2	"id": "resp_1234567890",
3	"object": "response",
4	"created_at": 1234567890,
5	"model": "openai/o4-mini",
6	"output": [
7	{
8	"type": "message",
9	"id": "msg_abc123",
10	"status": "completed",
11	"role": "assistant",
12	"content": [
13	{
14	"type": "output_text",
15	"text": "OpenRouter is a unified API for accessing multiple Large Language Model providers through a single interface. It allows developers to access 100+ AI models from providers like OpenAI, Anthropic, Google, and others with intelligent routing and automatic failover.",
16	"annotations": [
17	{
18	"type": "url_citation",
19	"url": "https://openrouter.ai/docs",
20	"start_index": 0,
21	"end_index": 85
22	},
23	{
24	"type": "url_citation",
25	"url": "https://openrouter.ai/models",
26	"start_index": 120,
27	"end_index": 180
28	}
29	]
30	}
31	]
32	}
33	],
34	"usage": {
35	"input_tokens": 15,
36	"output_tokens": 95,
37	"total_tokens": 110
38	},
39	"status": "completed"
40	}

1	{
2	"type": "url_citation",
3	"url": "https://example.com/article",
4	"start_index": 0,
5	"end_index": 50
6	}