OpenAI Web Search

OpenAI Web Search lets supported models search the web before answering and return text, search calls, and source citations in the response. It is useful for news, weather, product updates, and other time-sensitive queries.

If the data comes from your own database or business service, use Tool Calling to define a controlled tool instead of sending internal data to public web search.

Confirm the model and endpoint first

The presence of Web Search fields in a protocol does not mean that every model available to the current account supports search. First confirm the model and protocol in the Model marketplace, then review the corresponding API Reference.

Choose Responses or Chat

Endpoint	How to enable it	Result location
Responses	Add a Web Search Tool to `tools`	`web_search_call` and Message Output Item
Chat Completions	Use `web_search_options`	Assistant Message and `annotations`

Responses is better suited to applications that need to distinguish search calls, answers, and sources. Chat works well for projects that already use the message structure.

Search the web with Responses

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "tools": [
      {
        "type": "web_search_preview",
        "search_context_size": "medium"
      }
    ],
    "input": "What technology news is worth following today?"
  }'

The model might decide whether to perform a search based on the question. When a search occurs, the response output usually contains both a search call item and a text message item. See the Responses Reference for the complete Tool types.

Use Chat Completions

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "What technology news is worth following today?"
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

The Chat response body is in choices[].message.content. When structured citations are provided, they are in choices[].message.annotations. See the Chat Completions Reference for the complete fields.

Read answers and citations

{
  "output": [
    {
      "type": "web_search_call",
      "id": "ws_example",
      "status": "completed"
    },
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "According to the search results...",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://example.com/article",
              "title": "Source title"
            }
          ]
        }
      ]
    }
  ]
}

Do not save only the answer text. The application should retain the URL, title, and relationship between each citation and its text position, provide clickable sources in the interface, and apply safe new-tab attributes to external links.

Limit the search scope

When supported by the model and endpoint, you can configure the following search conditions:

Domain scope: Search only allowed sites, which is useful for medical, regulatory, or enterprise knowledge sources.
User location: Provide a country, city, region, or time zone to help return localized results.
Search context size: Choose an appropriate scope based on response quality, latency, and usage.
Source list: When supported, Responses can return sources consulted during the search, not only sources cited in the final answer.

These fields appear in different locations in Responses and Chat. See the corresponding Reference for exact names and limits.

Failures and fallback behavior

Symptom	Action
Search did not run	Determine whether the question needs current information and confirm that the model supports search
The answer has no citations	Do not fabricate sources; indicate that the response did not return displayable citations
Search failed	Use the response error to decide whether to retry, provide a non-search answer, or ask the user to try again later
Sources conflict	Show multiple sources and their update dates instead of letting the model hide important differences
A source is unavailable	Preserve the title and original URL, and tell the user that the page cannot currently be opened

External web content can contain incorrect information or malicious instructions aimed at the model. Do not trust content automatically just because it came from search results, and do not let search content bypass application permissions or trigger high-risk tools.

Pre-production checklist

The model and protocol explicitly support Web Search.
Answers, search calls, citations, and source lists are parsed separately.
Missing citations never produce fabricated links.
Domain and location information is sent only when the business requires it.
External content cannot bypass Tool Calling permissions or confirmation flows.
Search failures, timeouts, and empty results all have clear fallback behavior.

If a request fails, see Errors and troubleshooting. Before switching protocols, read Choose a protocol.