From 0baaf9125c0255139cc62c133c15a39aaae563b4 Mon Sep 17 00:00:00 2001
From: Cesar Garcia <128240629+Chesars@users.noreply.github.com>
Date: Fri, 6 Feb 2026 00:36:43 -0300
Subject: [PATCH] feat(web_search): add gpt-5-search-api model and docs
 clarifications (#20512)

* docs(web_search): clarify OpenAI search model requirements

- Add gpt-5-search-api to supported OpenAI search models
- Add warning that regular models (gpt-5, gpt-4.1) do NOT support web_search_options
- Add tip that web_search_options is optional for search models

* feat(models): add gpt-5-search-api pricing for OpenAI and Azure
---
 docs/my-website/docs/completion/web_search.md | 19 +++++++-
 ...odel_prices_and_context_window_backup.json | 46 +++++++++++++++++++
 2 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/docs/my-website/docs/completion/web_search.md b/docs/my-website/docs/completion/web_search.md
index db50c7b5bc5..9ba66c730f0 100644
--- a/docs/my-website/docs/completion/web_search.md
+++ b/docs/my-website/docs/completion/web_search.md
@@ -18,12 +18,29 @@ Each provider uses their own search backend:
 
 | Provider | Search Engine | Notes |
 |----------|---------------|-------|
-| **OpenAI** (`gpt-4o-search-preview`) | OpenAI's internal search | Real-time web data |
+| **OpenAI** (`gpt-4o-search-preview`, `gpt-4o-mini-search-preview`, `gpt-5-search-api`) | OpenAI's internal search | Real-time web data |
 | **xAI** (`grok-3`) | xAI's search + X/Twitter | Real-time social media data |
 | **Google AI/Vertex** (`gemini-2.0-flash`) | **Google Search** | Uses actual Google search results |
 | **Anthropic** (`claude-3-5-sonnet`) | Anthropic's web search | Real-time web data |
 | **Perplexity** | Perplexity's search engine | AI-powered search and reasoning |
 
+:::warning Important: Only Search Models Support `web_search_options`
+For OpenAI, only dedicated search models support the `web_search_options` parameter:
+- `gpt-4o-search-preview`
+- `gpt-4o-mini-search-preview`
+- `gpt-5-search-api`
+
+**Regular models like `gpt-5`, `gpt-4.1`, `gpt-4o` do not support `web_search_options`**
+:::
+
+:::tip The `web_search_options` parameter is optional
+Search models (like `gpt-4o-search-preview`) **automatically search the web** even without the `web_search_options` parameter.
+
+Use `web_search_options` when you need to:
+- Adjust `search_context_size` (`"low"`, `"medium"`, `"high"`)
+- Specify `user_location` for localized results
+:::
+
 :::info
 **Anthropic Web Search Models**: Claude models that support web search: `claude-3-5-sonnet-latest`, `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-latest`, `claude-3-5-haiku-20241022`, `claude-3-7-sonnet-20250219`
 :::
diff --git a/litellm/model_prices_and_context_window_backup.json b/litellm/model_prices_and_context_window_backup.json
index 7a4a50c2b5e..e6e61af14ee 100644
--- a/litellm/model_prices_and_context_window_backup.json
+++ b/litellm/model_prices_and_context_window_backup.json
@@ -3368,6 +3368,29 @@
         "supports_tool_choice": true,
         "supports_vision": true
     },
+    "azure/gpt-5-search-api": {
+        "cache_read_input_token_cost": 1.25e-07,
+        "input_cost_per_token": 1.25e-06,
+        "litellm_provider": "azure",
+        "max_input_tokens": 128000,
+        "max_output_tokens": 4096,
+        "max_tokens": 4096,
+        "mode": "chat",
+        "output_cost_per_token": 1e-05,
+        "search_context_cost_per_query": {
+            "search_context_size_high": 0.05,
+            "search_context_size_low": 0.03,
+            "search_context_size_medium": 0.035
+        },
+        "supports_function_calling": true,
+        "supports_parallel_function_calling": true,
+        "supports_prompt_caching": true,
+        "supports_response_schema": true,
+        "supports_system_messages": true,
+        "supports_tool_choice": true,
+        "supports_vision": true,
+        "supports_web_search": true
+    },
     "azure/gpt-5-2025-08-07": {
         "cache_read_input_token_cost": 1.25e-07,
         "input_cost_per_token": 1.25e-06,
@@ -18393,6 +18416,29 @@
         "supports_service_tier": true,
         "supports_vision": true
     },
+    "gpt-5-search-api": {
+        "cache_read_input_token_cost": 1.25e-07,
+        "input_cost_per_token": 1.25e-06,
+        "litellm_provider": "openai",
+        "max_input_tokens": 128000,
+        "max_output_tokens": 4096,
+        "max_tokens": 4096,
+        "mode": "chat",
+        "output_cost_per_token": 1e-05,
+        "search_context_cost_per_query": {
+            "search_context_size_high": 0.05,
+            "search_context_size_low": 0.03,
+            "search_context_size_medium": 0.035
+        },
+        "supports_function_calling": true,
+        "supports_parallel_function_calling": true,
+        "supports_prompt_caching": true,
+        "supports_response_schema": true,
+        "supports_system_messages": true,
+        "supports_tool_choice": true,
+        "supports_vision": true,
+        "supports_web_search": true
+    },
     "gpt-5.1": {
         "cache_read_input_token_cost": 1.25e-07,
         "cache_read_input_token_cost_priority": 2.5e-07,