Data governance When to use How Web Search works Enable Web Search Controlling external web access Code examples Security Monitoring with CloudTrail Acceptable use

Web Search

Web Search is a built-in tool that provides web search capability in Amazon Bedrock. When you enable it, supported models can retrieve current information from the web during a request and use it to ground their answers, instead of relying only on the data they were trained on. Responses include citations to the sources the model used. Web Search is hosted and built by AWS, and your data stays within the AWS boundary by default.

Data governance

By default, when using the AmazonBedrockFullAccess policy, Web Search is served from the Amazon Bedrock web index and cache, and your request data does not leave the AWS boundary for retrieval. You can also use IAM to enforce this at the policy level. Depending on the model you are using, your data is subject to the automated Amazon Bedrock abuse detection mechanisms.

When to use Web Search

Web Search is useful whenever an answer depends on information that is more recent, more specialized, or more authoritative than a model's parametric knowledge. Recency is one common case: current events, recent product releases, prices, or documentation for a new library version. It is equally useful for long-tail or specialized questions where the model's knowledge is thin or imprecise, such as niche APIs, specific configuration values, or domain-specific facts, and for cases where you want a grounded, citable source rather than a recollection.

How Web Search works

Because the tool runs inside Amazon Bedrock, you do not need to host a search index, manage crawlers, or write the tool-call loop yourself. You add the tool to your Amazon Bedrock inference request, and the model invokes it as needed. Web Search provides current information to the model, enabling the model to return grounded answers with citations.

When Web Search is enabled, the model decides whether a request needs current information. If it does, the model issues one or more search queries to the Web Search tool and receives a set of observations drawn from a web index built and maintained by Amazon. Each observation includes a title, a source URL, and a content snippet. The model then composes an answer grounded in those results and adds citations that point back to the sources.

If the first set of results is not enough to answer the question, the model can reformulate its query using what it found and search again within the same turn. When the results do not support an answer, the model tells you so rather than filling the gap from its training data.

Search and Fetch operations

Web Search is built from two operations:

Search – Returns titles, URLs, and snippets from the Amazon Bedrock web index and knowledge graph for high-confidence facts.
Fetch – Retrieves cached page content for a specific URL from the Amazon Bedrock cache. If the result is unavailable in the cache, the model may choose to either notify you or build a response based on the best information it has.

By default, both operations are served entirely from within the AWS service boundary using the Amazon Bedrock web index and cache, a snapshot of web content hosted inside AWS, rather than fetching from the live web at request time. The external_web_access parameter in the Responses API and the bedrock-websearch:ExternalWebAccess IAM permission govern whether search and fetch may reach the external web directly. For details, see Controlling external web access.

Supported models

Web Search is available for OpenAI GPT models served through the Amazon Bedrock bedrock-mantle endpoint, using the Responses API. It is currently supported on openai.gpt-5.4, openai.gpt-5.5, and openai.gpt-5.6 (luna, terra, and sol). For Web Search pricing, refer to the Amazon Bedrock pricing page.

Regional availability

Web Search processes queries in-Region in three US Regions:

Region	Region code
US East (N. Virginia)	`us-east-1`
US East (Ohio)	`us-east-2`
US West (Oregon)	`us-west-2`

Web Search is strictly regional. Each Region operates its own search and fetch tier, and queries, fetches, index data, and results are not routed across Regions. A query issued in a given Region stays within that Region's boundary.

Enable Web Search

To use Web Search, the IAM identity behind your request must be allowed to call the Web Search actions. For the required permissions and example policies, see Identity and access management for Web Search.

Set your environment

Set the following before running the examples:


export OPENAI_API_KEY="your-amazon-bedrock-api-key"
export OPENAI_BASE_URL="https://bedrock-mantle.us-west-2.api.aws/openai/v1"

Add the Web Search tool to a request

To enable Web Search, add a tool of type web_search to the tools array in your request. The model uses the tool only when it determines the request needs current information. For runnable examples, see Code examples.

Controlling external web access

By default, Web Search is served entirely from the Amazon Bedrock web index and cache, and no request data leaves the AWS boundary for retrieval. Whether search and fetch may reach the external web is governed by two controls that work together: the external_web_access parameter in the Responses API and the bedrock-websearch:ExternalWebAccess IAM permission.

The external_web_access parameter defaults to true, matching the OpenAI Responses API so that your call does not have to change. The AmazonBedrockFullAccess policy grants the basic Web Search actions — bedrock-websearch:InvokeSearch and bedrock-websearch:InvokeFetch — but does not grant bedrock-websearch:ExternalWebAccess. As a result, a request that leaves external_web_access at true from an identity that does not hold ExternalWebAccess returns a 403 AccessDenied on the authorization check. The model does not fail the request: it grounds its answer in Search and cached Fetch and reports that it could not obtain external web access.

To make a request that does not hit this error, use one of the two approaches below.

Keep requests within the AWS boundary

Set "external_web_access": false on the tool. This does not require the ExternalWebAccess permission, retrieval is served entirely from the Amazon Bedrock web index and cache, and your request data does not leave the AWS boundary. Because AmazonBedrockFullAccess does not grant ExternalWebAccess, this configuration is safe by default.


response = client.responses.create(
    model="openai.gpt-5.5",
    input="Summarize recent guidance on AWS Lambda cold starts.",
    tools=[{"type": "web_search", "external_web_access": False}],
)


curl "https://bedrock-mantle.us-west-2.api.aws/openai/v1/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai.gpt-5.5",
    "input": "Summarize recent guidance on AWS Lambda cold starts.",
    "tools": [{"type": "web_search", "external_web_access": false}]
  }'

Enable external web access

Grant bedrock-websearch:ExternalWebAccess to the request identity and leave external_web_access at its default of true. This configuration governs whether search and fetch may reach the external web. Today, retrieval is served entirely from the Amazon Bedrock web index and cache, so no request data leaves the AWS boundary even when this permission is granted. In a future release, this configuration may allow search and fetch to retrieve content from the live external web, at which point request data may leave the AWS boundary. External web access is disabled by default (that is, bedrock-websearch:ExternalWebAccess is disallowed), and any future change will require allowing bedrock-websearch:ExternalWebAccess as an explicit opt-in before it takes effect. External web access remains under your control: it applies only because you granted the permission and left the parameter enabled.

Code examples

Responses API


from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="openai.gpt-5.5",
    input="What are the most significant AWS launches announced this month?",
    tools=[{"type": "web_search", "external_web_access": False}],
)

print(response.output_text)

The response includes the grounded answer text together with url_citation annotations that point back to the sources:


{
  "content": [
    {
      "annotations": [
        {
          "end_index": 573,
          "start_index": 441,
          "title": "Upgrade Amazon EKS clusters with confidence using Kubernetes version rollbacks | AWS News Blog",
          "type": "url_citation",
          "url": "https://aws.amazon.com/blogs/aws/upgrade-amazon-eks-clusters-with-confidence-using-kubernetes-version-rollbacks/"
        },
        {
          "end_index": 1094,
          "start_index": 888,
          "title": "AWS Weekly Roundup: AWS Builder Center at 1 year, Network Scanning in Security Hub, Loom for AWS, and more (July 13, 2026) | AWS News Blog",
          "type": "url_citation",
          "url": "https://aws.amazon.com/blogs/aws/aws-weekly-roundup-aws-builder-center-at-one-year-network-scanning-in-security-hub-loom-for-aws-and-more-july-13-2026/"
        },
        {
          "end_index": 1837,
          "start_index": 1414,
          "title": "AWS Weekly Roundup: One-click Lambda setup prompt, OpenAI GPT-5.6 models on Bedrock, and more (July 20, 2026) | AWS News Blog",
          "type": "url_citation",
          "url": "https://aws.amazon.com/blogs/aws/aws-weekly-roundup-one-click-lambda-setup-prompt-openai-gpt-5-6-models-on-bedrock-and-more-july-20-2026/"
        }
      ],
      "logprobs": [],
      "text": "As of **July 30, 2026**, the most significant AWS launches this month:\n\n1. **Amazon EKS Kubernetes version rollbacks** — EKS now lets admins roll back a Kubernetes version upgrade within **seven days**, effectively adding an “undo” path for cluster upgrades and reducing upgrade risk for large or regulated Kubernetes fleets. It’s available at no additional cost in commercial Regions where EKS is available. ([aws.amazon.com](https://aws.amazon.com/blogs/aws/upgrade-amazon-eks-clusters-with-confidence-using-kubernetes-version-rollbacks/))\n\n2. **AWS Security Hub Network Scanning + Azure support** — Security Hub added active Network Scanning to find resources actually reachable from the public internet, and also expanded unified security management to **Microsoft Azure** resources, making this a notable multi-cloud security/posture-management move. ([aws.amazon.com](https://aws.amazon.com/blogs/aws/aws-weekly-roundup-aws-builder-center-at-one-year-network-scanning-in-security-hub-loom-for-aws-and-more-july-13-2026/))\n\n3. **New frontier models on Amazon Bedrock: Claude Sonnet 5, Claude Opus 5, and OpenAI GPT-5.6 models** — AWS added major new model choices to Bedrock this month: Anthropic’s Claude Sonnet 5 and Claude Opus 5, plus OpenAI GPT-5.6 Sol, Terra, and Luna, expanding Bedrock’s role as a multi-model enterprise AI platform. ([aws.amazon.com](https://aws.amazon.com/blogs/aws/aws-weekly-roundup-one-click-lambda-setup-prompt-openai-gpt-5-6-models-on-bedrock-and-more-july-20-2026/))",
      "type": "output_text"
    }
  ],
  "id": "msg_dcda8e4b477f5a1d96bfbcadefef7a77",
  "phase": "final_answer",
  "role": "assistant",
  "status": "completed",
  "type": "message"
}

Direct HTTPS request

If you are not using the OpenAI SDK, send the request directly to the Responses endpoint. The tools field carries the Web Search tool.


curl "https://bedrock-mantle.us-west-2.api.aws/openai/v1/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai.gpt-5.5",
    "input": "What are the most significant AWS launches announced this month?",
    "tools": [{"type": "web_search", "external_web_access": false}]
  }'

Reading citations from the response

Web Search returns citations as url_citation annotations attached to the text. Each annotation carries the source title and URL and the character span in the answer it supports. Retain and display these to end users.


from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="openai.gpt-5.5",
    input="What are the most significant AWS launches announced this month?",
    tools=[{"type": "web_search", "external_web_access": False}],
)

# The grounded answer
print(response.output_text)

# The sources behind it
for item in response.output:
    if item.type == "message":
        for block in item.content:
            if block.type == "output_text":
                for ann in block.annotations:
                    if ann.type == "url_citation":
                        print(f"- {ann.title}: {ann.url}")

If you are working with the raw JSON (for example, from a direct HTTPS call), the same data lives at output[].content[].annotations[]:


jq '.output[] | select(.type=="message") | .content[]
      | select(.type=="output_text") | .annotations[]
      | select(.type=="url_citation") | {title, url, start_index, end_index}' response.json

Streaming responses

The Responses API streams the answer as it is generated. Text arrives as response.output_text.delta events, and each citation arrives as a response.output_text.annotation.added event as the model grounds a statement.


from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="openai.gpt-5.5",
    input="What are the most significant AWS launches announced this month?",
    tools=[{"type": "web_search", "external_web_access": False}],
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.output_text.annotation.added":
        ann = event.annotation
        print(f"\n[source] {ann['title']}: {ann['url']}")

Over the wire, the annotation event looks like this:


event: response.output_text.annotation.added
data: {"type":"response.output_text.annotation.added","annotation":{"type":"url_citation","title":"News and Updates from the July 2025 Pokémon Presents","url":"https://www.pokemon.com/us/pokemon-news/...","start_index":589,"end_index":698},"annotation_index":2,"content_index":0,"item_id":"msg_...","output_index":1}

Security

Web Search on Amazon Bedrock uses AWS Identity and Access Management (IAM) to control who can run searches and fetches and in which Regions. The IAM service prefix for Web Search is bedrock-websearch. For the full list of actions, managed policies, condition keys, example policies, and administrator controls for disabling Web Search, see Identity and access management for Web Search.

Monitoring with CloudTrail

Web Search on Amazon Bedrock is integrated with AWS CloudTrail. CloudTrail captures API activity for Web Search as data events, so you can audit who invoked the tool, when, and from where. For the fields captured, how to enable data event logging, and what is intentionally excluded, see Monitor Web Search.

Acceptable use

If you use Web Search on Amazon Bedrock, Amazon Bedrock provides Web Search results (“Search Results”) to supported models, which the model may use to generate its response. You are responsible for your use, and any use by your end users, of model outputs that incorporate Search Results. You must retain and display the source citations and links provided in model outputs in any output you surface to your end users. You may not use Web Search to (a) extract, store, or reproduce content from Search Results in bulk, or (b) build or populate a competing index or database.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Anthropic Claude tool use

Projects