Skip to content

GPT Web Search

Allows models to search the web for the latest information before generating a response. This gives models access to up-to-date information on the internet and provides answers with source citations.

There are currently two main ways to use the Web Search tool on our platform (compatible with the native OpenAI interface): Responses API and Chat Completions API.

Basic Usage

1. Using the Responses API

In the Responses API, you can configure the web_search tool in the tools array. Just like other tools, the model will decide on its own whether to conduct a web search based on the content of the input prompt.

Our Platform Example (New API Platform)

curl "https://api-cs-al.naci-tech.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
        "model": "gpt-5",
        "tools": [{"type": "web_search"}],
        "input": "What were the positive news stories today?"
    }'

OpenAI Official Example

curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-5",
        "tools": [{"type": "web_search"}],
        "input": "what was a positive news story from today?"
    }'

2. Using the Chat Completions API

When using Chat Completions, the model will always retrieve information from the web before responding to your query. To use this feature, you must specify a specific search model (such as gpt-4o-search-preview) and enable search via the web_search_options parameter.

Our Platform Example (New API Platform)

curl "https://api-cs-al.naci-tech.com/v1/chat/completions" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-4o-search-preview",
        "web_search_options": {},
        "messages": [{
            "role": "user",
            "content": "What were the positive news stories today?"
        }]
    }'

OpenAI Official Example

curl "https://api.openai.com/v1/chat/completions" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-4o-search-preview",
        "web_search_options": {},
        "messages": [{
            "role": "user",
            "content": "What was a positive news story from today?"
        }]
    }'

Output and citations

By default, the model's response will contain inline citations for the URLs found in the web search results.

Responses API Output

The Responses output will contain two parts: 1. A web_search_call output item, containing the ID of the search call and the action executed (e.g., search, open_page). 2. A message output item, containing the text result (message.content[0].text) and annotations for the cited URLs (message.content[0].annotations).

In the url_citation annotation object, the URL, title, and position of the cited source will be included.

[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa05...",
    "status": "completed"
  },
  {
    "id": "msg_67c9fa07...",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, there were multiple news reports about...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

Chat Completions API Output

The returned choices array will contain: * message.content: Contains the text result of the model, along with any inline citations. * message.annotations: Contains a list of cited URLs, also using url_citation to provide citation details and the start_index and end_index within the content.

[
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The model's reply content is here...",
      "refusal": null,
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "end_index": 985,
            "start_index": 764,
            "title": "Page title...",
            "url": "https://..."
          }
        }
      ]
    },
    "finish_reason": "stop"
  }
]

Domain filtering

Domain filtering allows you to limit your search results to a specific set of domains. You can set an allowlist of up to 100 URLs using the filters.allowed_domains parameter.

Note: Domain filtering is currently only available in the web_search tool within the Responses API.

Our Platform Example (New API Platform)

curl "https://api-cs-al.naci-tech.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
  "model": "gpt-5",
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": [
          "pubmed.ncbi.nlm.nih.gov",
          "www.who.int",
          "www.cdc.gov"
        ]
      }
    }
  ],
  "input": "Search for related studies on Semaglutide for the treatment of diabetes."
}'

OpenAI Official Example

curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-5",
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": [
          "pubmed.ncbi.nlm.nih.gov",
          "www.who.int",
          "www.cdc.gov"
        ]
      }
    }
  ],
  "input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
}'

Sources

To view all URLs retrieved during the web search, you can use include: ["web_search_call.action.sources"]. Unlike inline citations which only show the most relevant references, sources return the full list of URLs the model consulted when forming its response.

Our Platform Example (New API Platform)

curl "https://api-cs-al.naci-tech.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
  "model": "gpt-5",
  "tools": [{"type": "web_search"}],
  "tool_choice": "auto",
  "include": ["web_search_call.action.sources"],
  "input": "Explain the latest advancements in quantum computing."
}'

OpenAI Official Example

curl "https://api.openai.com/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-5",
  "reasoning": { "effort": "low" },
  "tools": [{"type": "web_search"}],
  "tool_choice": "auto",
  "include": ["web_search_call.action.sources"],
  "input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
}'

User location

To optimize search results based on geographic location, you can specify an approximate user location (including country, city, region, or timezone) using the user_location parameter.

Usage in the Responses API

Our Platform Example (New API Platform)

curl "https://api-cs-al.naci-tech.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
        "model": "o4-mini",
        "tools": [{
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "CN",
                "city": "Shanghai",
                "region": "Shanghai"
            }
        }],
        "input": "What are the recommended attractions near me?"
    }'

OpenAI Official Example

curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "o4-mini",
        "tools": [{
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "GB",
                "city": "London",
                "region": "London"
            }
        }],
        "input": "What are the best restaurants near me?"
    }'

Usage in the Chat Completions API

In Chat models, you can include user_location within web_search_options.

Our Platform Example (New API Platform)

curl "https://api-cs-al.naci-tech.com/v1/chat/completions" \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-4o-search-preview",
        "web_search_options": {
            "user_location": {
                "type": "approximate",
                "approximate": {
                    "country": "CN",
                    "city": "Beijing",
                    "region": "Beijing"
                }
            }
        },
        "messages": [{
            "role": "user",
            "content": "What is the best restaurant near me?"
        }]
    }'

OpenAI Official Example

curl "https://api.openai.com/v1/chat/completions" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-4o-search-preview",
        "web_search_options": {
            "user_location": {
                "type": "approximate",
                "approximate": {
                    "country": "GB",
                    "city": "London",
                    "region": "London"
                }
            }
        },
        "messages": [{
            "role": "user",
            "content": "What are the best restaurants near me?"
        }]
    }'

Live internet access

You can control whether the tool fetches live content or only uses indexed (offline/cached) results by setting external_web_access: false on the web_search tool in the Responses API. The default is true.

Note: Preview versions (web_search_preview) will ignore this parameter and always behave as true.

Our Platform Example (New API Platform)

curl "https://api-cs-al.naci-tech.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "gpt-5",
    "tools": [
      { "type": "web_search", "external_web_access": false }
    ],
    "tool_choice": "auto",
    "input": "Please find the sunrise time in Paris today and cite the source."
  }'

OpenAI Official Example

curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5",
    "tools": [
      { "type": "web_search", "external_web_access": false }
    ],
    "tool_choice": "auto",
    "input": "Find the sunrise time in Paris today and cite the source."
  }'

API compatibility

Web search currently supports: * Responses API: You can use the general version web_search tool or the early version web_search_preview tool. * Chat Completions API: You must use a dedicated search model to enable Web Search. Currently supported models include: * gpt-5-search-api * gpt-4o-search-preview * gpt-4o-mini-search-preview

Limitations

  • The Web Search tool currently does not support the gpt-5 model with a minimal reasoning configuration, nor models like gpt-4.1-nano.
  • When used as a tool in the Responses API, its rate limit is the same as the tier rate limit of the selected model.
  • The Web Search feature will be subject to a 128,000 context window limit (including the gpt-4.1 and gpt-4.1-mini series).

Usage notes

API Availability Rate limits
Responses
Chat Completions		 Shares the same rate limit as the model being called as the underlying tool.