Amazon Bedrock Web Search: Setup on bedrock-mantle, Domain Filtering, User Location, $12 per 1,000 Queries, IAM, and Why Fetch Fails Silently With AmazonBedrockFullAccess

Amazon Bedrock Web Search is a built-in tool that lets a model look things up on the web while it answers, then cite its sources. You enable it by adding {"type": "web_search"} to the tools list of a Responses API request on the bedrock-mantle endpoint, with an OpenAI GPT-5.4 or later model, in US East (N. Virginia), US East (Ohio), US West (Oregon) or GovCloud (US-West). It costs $12.00 per 1,000 search queries plus the model's normal token charges, and since October 23, 2026 it supports domain filtering (up to 100 allowed or 100 blocked domains) and user location. Here is the trap almost everyone walks into. The tool's external_web_access setting defaults to true, but the common AmazonBedrockFullAccess policy does not grant external access. With that combination, every page fetch fails silently: the request still returns HTTP 200, the answer still carries citations, and nothing tells you the model never read the pages it cites. Set external_web_access to false explicitly and the fetches work from Amazon's cache. This guide covers setup, IAM, filters, location, cost, Codex, monitoring and every pitfall.

Jake spends an hour every morning checking two parts suppliers' websites for prices on the screens he stocks. Ethan wanted to hand that to a model: ask it "what does a Galaxy S26 screen cost at our two suppliers today?" and get an answer with links. "Can it just read the websites?" Jake asked. "It can," Ethan said, "if I stop it reading the rest of the internet, and if I set one switch that nobody notices is wrong." This is that switch, and the rest of the setup.

New to Bedrock? Amazon Bedrock is AWS's service for calling AI models through an API, without running the models yourself. Our plain-English Bedrock guide covers the basics. Bedrock has two inference endpoints, bedrock-runtime and the newer bedrock-mantle, and Web Search lives only on Mantle; our Mantle vs bedrock-runtime guide explains the difference and the base URLs.

What is Amazon Bedrock Web Search?

Web Search is a server-side tool built and hosted by AWS. You do not run a search engine, write a crawler or code the tool-call loop. You add the tool to a request, and the model decides on its own whether the question needs current information. If it does, it sends one or more search queries, reads the results, and writes an answer with url_citation annotations that point back to the sources. If the first results are thin, it can reformulate and search again within the same turn, and if the results do not support an answer, it says so rather than guessing from its training data.

Under the hood it is two operations:

• Search returns a ranked list of "observations": a title, a URL and a snippet each. Results come from a web index Amazon builds, which includes publicly available web content, licensed content and Amazon Knowledge Graph data for high-confidence facts. Search never goes to the live web.
• Fetch reads the content of one specific page. By default it uses Amazon's cache. Only with external web access switched on (both a request parameter and an IAM permission) can it go to the live web when a page is not cached.

Here is what it supports on October 24, 2026:

Two limits surprise people. It is not available on bedrock-runtime, even through bedrock-runtime's own Responses API, because it is a server-side tool. And it works only with OpenAI's GPT-5.4 and later models today, so a Claude, Nova or Llama model on Bedrock cannot use it; for those you would build your own search tool with client-side tool use. "Every region stays in its own lane, too," Ethan told Jake. "A search sent in Oregon is answered in Oregon. Nothing gets routed across the country."

The trap: why Fetch fails silently with AmazonBedrockFullAccess

This is the most important paragraph on the page. Two settings decide whether Fetch may use the live web:

• the external_web_access parameter on the tool, which defaults to true (to match OpenAI's own Responses API, so ported code does not need changes), and
• the bedrock-websearch:ExternalWebAccess IAM permission, which none of the general Bedrock policies grant, including AmazonBedrockFullAccess, AmazonMantleFullAccess, AmazonBedrockLimitedAccess and AmazonBedrockMantleInferenceAccess.

Leave the parameter at its default with one of those policies, and each Fetch attempt asks for external access the identity does not have. Fetch is denied at the authorization check, before it even reads the cache. But the request as a whole does not fail. The model carries on with the search snippets it already has, returns HTTP 200, and still adds url_citation annotations. The consequence is easy to miss: the response is not guaranteed to mention the failure, and a citation does not mean the cited page was fetched. You get answers built from snippets while believing they came from full pages.

There are two correct configurations, and you should pick one on purpose:

1. Stay inside AWS (recommended default). Set "external_web_access": false explicitly. Search uses Amazon's index, Fetch uses Amazon's cache, your request data does not leave the AWS boundary, and the general Bedrock policies are enough because they include InvokeFetch.
2. Allow the live web. Grant bedrock-websearch:ExternalWebAccess (most simply by attaching AmazonBedrockExternalWebSearchFullAccess) and leave external_web_access at true. Fetch then checks the cache first and goes to the live web only on a miss.

The broken middle state, parameter true without the permission, is what you get by doing nothing. "So the default is the broken one," Jake said. "The default is the one that looks fine," Ethan said, "which is worse."

How to set up Bedrock Web Search, step by step

1. Pick a supported Region: us-east-1, us-east-2 or us-west-2 (or us-gov-west-1 in GovCloud). Web Search processes everything in the Region you call.
2. Give the identity permission. It needs bedrock-websearch:InvokeSearch and bedrock-websearch:InvokeFetch, plus model inference on Mantle. AmazonBedrockFullAccess and AmazonMantleFullAccess already include both Web Search actions; for least privilege, use the custom policy in the IAM section.
3. Create a Bedrock API key for the OpenAI-compatible endpoint (or use your usual IAM credentials with an SDK that signs Mantle requests). Our Mantle guide covers both ways.
4. Point the OpenAI SDK at Mantle with two environment variables:

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

5. Install the SDK: pip install --upgrade openai.
6. Send a request with the tool, setting external_web_access explicitly (below).

from openai import OpenAI

client = OpenAI()   # reads OPENAI_API_KEY and OPENAI_BASE_URL

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

The same request with curl:

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.6-terra",
       "input": "Summarize recent guidance on AWS Lambda cold starts.",
       "tools": [{"type": "web_search", "external_web_access": false}]}'

Reading the citations. The answer text comes with annotations, each of type url_citation with a title, a url, and start_index/end_index marking which part of the text it supports. To show sources in your app, walk the output items and collect them:

for item in response.output:
    for part in getattr(item, "content", None) or []:
        for a in getattr(part, "annotations", None) or []:
            if a.type == "url_citation":
                print(a.title, "-", a.url)

Show those links to users. A grounded answer is only as good as the reader's ability to check it, and the links are how they do.

Domain filtering: allowed_domains and blocked_domains

New on October 23, 2026, the filters parameter limits which sites Web Search results may come from. You can list up to 100 allowed domains to keep results to trusted sources, or up to 100 blocked domains to keep certain sites out. Three rules for writing the list:

• Write bare domains, without http:// or https://.
• Each entry also matches its subdomains, so aws.amazon.com covers docs.aws.amazon.com too.
• Use allowed domains when you need answers grounded only in specific sites, and blocked domains when the open web is fine except for a few sources.

tools=[{
    "type": "web_search",
    "external_web_access": False,
    "filters": {"allowed_domains": ["aws.amazon.com", "docs.aws.amazon.com"]},
}]

For Jake's price checker, Ethan listed the two suppliers' domains as allowed, so every answer is grounded in their pages and nowhere else. A blocked list suits the opposite case: a research assistant that may read anything except, say, content farms or a competitor's site.

One subtlety matters for strict source control. Filters restrict the results Search returns. Fetch is a separate action, and it can be asked for any URL the model produces, including one it generates from its own knowledge or one a user pastes in. If an answer must come only from approved sources, combine the domain filter with external_web_access: false, keep the system prompt explicit about using only those sources, and audit Fetch calls in CloudTrail. Filters are a strong steer, not a firewall.

User location: localize results (and why "UK" is rejected)

Also new on October 23, user_location tells Web Search where the user is, so location-dependent questions ("which stores near me stock this?", "is this service available in my country?") get local results. Depending on the model, the location is used by the model, the search service, or both. Without it, the location defaults to the United States.

tools=[{
    "type": "web_search",
    "external_web_access": False,
    "user_location": {
        "type": "approximate",
        "country": "GB",
        "city": "Manchester",
        "region": "England",
        "timezone": "Europe/London",
    },
}]

The field rules are strict in one place:

• country must be an assigned ISO 3166-1 alpha-2 code. It is not case-sensitive (de works as DE), but unassigned and user-assigned codes are rejected, including UK and XK. For the United Kingdom, use GB.
• region and city are free-form text.
• timezone takes an IANA time zone name, such as America/Chicago or Asia/Kolkata.

Only pass location you are allowed to use. If it comes from a user's device or account, tell them, and use the coarsest level that answers the question. A country is often enough; a city rarely needs to be more than a city.

search_context_size: low, medium or high

search_context_size sets how many observations each Search call can hand the model:

Each observation is a title, a URL and a snippet, and the budget is shared when one Search call contains several queries; the service can return fewer than the maximum. Two things it does not do. It does not limit how many Search calls the model makes, so a hard question can still trigger several searches at low. And it does not change the per-query price; it changes how many tokens of results the model reads, which shows up in your model bill. For a price checker that asks one narrow question, Ethan set low.

external_web_access: keeping data inside AWS, or not

With external_web_access: false, Search is served from Amazon's index and Fetch from Amazon's cache, and nothing about your request leaves the AWS boundary. With it true (and the permission granted), Fetch can retrieve live pages when the cache misses, and at that moment your request data may leave AWS.

There is a security reason to prefer false beyond data residency: exfiltration. A model working on sensitive data could, through a crafted prompt or a poisoned document, encode that data into a URL and then try to fetch it, delivering your data to whoever owns that domain. With live fetches disabled, that path is closed. Use false whenever sensitive data is involved; it is the sensible default for most business use.

Turn the live web on only when you need pages Amazon's cache does not have, such as fresh pages on small sites, and then grant ExternalWebAccess only to the identities that need it. Search itself never uses the live web either way, so the decision is purely about Fetch.

IAM for Web Search: actions, managed policies and example policies

Web Search has its own IAM prefix, bedrock-websearch, with three actions, all on the * resource:

• bedrock-websearch:InvokeSearch: run a search; returns titles, URLs and snippets from Amazon's index; makes no outbound calls.
• bedrock-websearch:InvokeFetch: read a page; cache only, unless the request enables external access and the identity has it.
• bedrock-websearch:ExternalWebAccess: let Fetch go to the live web after a cache miss.

Both tools are shown to the model whenever web_search is in the request; IAM does not change what the model sees, only what succeeds when it tries. With InvokeSearch but not InvokeFetch, the model answers from snippets only. With InvokeFetch but not InvokeSearch, it cannot discover sources, but it can still fetch any URL it knows or is given, so denying Search alone does not confine the model to your URLs.

The managed policies, and the one with a misleading name:

That fourth row is the second trap on this page. "ReadOnly" sounds like the cautious choice, but the current AmazonBedrockExternalWebSearchReadOnly grants exactly the same three actions as AmazonBedrockExternalWebSearchFullAccess, including live web access. It exists for naming conventions, not as a restriction. If you need a narrower set, write your own policy. Least privilege for the common, inside-AWS setup, limited to one Region:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "AllowWebSearchInRegion",
    "Effect": "Allow",
    "Action": ["bedrock-websearch:InvokeSearch", "bedrock-websearch:InvokeFetch"],
    "Resource": "*",
    "Condition": {"StringEquals": {"aws:RequestedRegion": "us-west-2"}}
  }]
}

Add bedrock-websearch:ExternalWebAccess to the action list only for identities that truly need live fetches. The only Web Search condition key is the global aws:RequestedRegion.

Turning Web Search off. Administrators can disable it at three levels: across an organization with a service control policy that denies bedrock-websearch:*, in one account with an IAM deny on the same actions, or in particular Regions with a deny that uses aws:RequestedRegion. The organization-wide version:

{
  "Version": "2012-10-17",
  "Statement": [{"Sid": "DenyAllWebSearch", "Effect": "Deny", "Action": "bedrock-websearch:*", "Resource": "*"}]
}

Test your real request patterns before and after any restriction. The model decides when to search and fetch, so a policy change can quietly change answer quality rather than producing errors.

Bedrock Web Search pricing: $12 per 1,000 queries, plus tokens

The AWS price list (October 16, 2026) charges $12.00 per 1,000 Web Search queries, which is $0.012 per query, in all three US commercial Regions. That is on top of the model's normal per-token charges, and search results add input tokens, because the model reads every observation it receives. Three things drive the bill:

• Queries per request. The model decides how many searches to run, and a hard question can take several, including reformulated retries.
• Result volume. search_context_size and page fetches add input tokens to every turn that uses them.
• Auditing. CloudTrail data events, which you need to see denied fetches, are billed separately by CloudTrail.

Some worked examples, for the search fee only:

• Jake's price checker: 30 questions a day at about 2 queries each is 60 queries, $0.72 a day, about $22 a month, to replace an hour of checking every morning.
• A support assistant: 10,000 conversations a month, a third of them needing a search at 1.5 queries each, is 5,000 queries, $60 a month.
• A research agent: 500 deep tasks a month at 12 queries each is 6,000 queries, $72, and here the extra input tokens from high context and page fetches will usually cost more than the queries themselves.

To keep costs predictable, use low context for narrow questions, ask for concise answers, and track Web Search usage per project; our guide to Bedrock cost tracking with inference profiles shows how to tag spending by application.

Using Bedrock Web Search with Codex

OpenAI's Codex coding agent can run on Bedrock through the bedrock-mantle endpoint, and on supported models it can use Web Search. You need the Codex desktop app or the Codex CLI version 0.147.0 or later; our Codex CLI install guide covers updating it.

Codex needs no IAM setup beyond the standard Web Search permissions: the identity behind your Bedrock API key must be allowed bedrock-websearch:InvokeSearch and bedrock-websearch:InvokeFetch, which AmazonBedrockFullAccess already grants. Codex uses text-only Web Search (titles, URLs and snippets from Amazon's index and cache), and it sets external_web_access to false on every request, so your code and prompts stay inside AWS. In other words, Codex already avoids the silent-failure trap that catches hand-written code.

Monitoring Web Search with CloudTrail

Web Search activity is recorded in CloudTrail as data events, which are not logged by default. To capture them, create a trail or event data store and enable data event logging for Web Search; CloudTrail charges for data events. Each recorded call shows who invoked it, when, which bedrock-websearch action, the source identity and the account and Region.

Fetch events carry the details you need to debug the trap above:

• requestParameters.fetchMode: USE_CACHE_ONLY or USE_CACHE_WITH_EXTERNAL_WEB_FALLBACK (for a denied call, the mode that was requested).
• requestParameters.urlCount and additionalEventData.failedUrlCount: how many URLs were asked for, and how many returned nothing.
• additionalEventData.fetchedSources: how many pages came from CACHE and how many from EXTERNAL_WEB.
• errorCode: AccessDenied with no fetchedSources: the silent failure, caught. This is the only reliable signal, because the API response can still be 200.

By design, CloudTrail never records the query text, the URLs or the raw results; query text is treated like an inference prompt. So CloudTrail tells you that the model searched and fetched, and whether it worked, but not what it searched for.

Data retention and privacy

Web Search does not persist your prompt or the queries the model writes; neither is written to durable storage. Search results (titles, URLs, snippets) are not stored against your account, identity or prompt. Your prompts and tool calls are not sent to a third-party search provider; the index and cache are built and run by Amazon. Pages fetched from the live web, when you allow it, go into a temporary live-fetch cache so publishers are not hit too often. Retention of your prompts and model outputs by Bedrock itself follows your account or project data retention mode, and depending on the model, requests may pass through Bedrock's automated abuse detection.

For most teams that adds up to a clear policy: keep external_web_access off, and the whole search path stays inside AWS with nothing about your request kept afterwards.

Bedrock Web Search vs AgentCore Web Search: two different tools

Search for "Bedrock web search domain filtering" and you will meet a second product with almost the same name: Web Search in Amazon Bedrock AgentCore, AWS's platform for building and running agents. It is a separate tool, reached through an AgentCore Gateway rather than a model's Responses API, and it gained its own domain and date filters on August 19, 2026. The two are easy to mix up, so here they are side by side:

Pick by how you build. If a single model call should look things up and cite sources, use the Responses API tool on this page. If you are building an agent on AgentCore, with its own gateway, identity and tools, or you need web search in Europe or Tokyo today, use the AgentCore version. Only the AgentCore one filters by publication date, which matters for "news from the last week" style questions; on Mantle you would put the date range in the prompt instead.

Can Claude use web search on Bedrock? The workaround

Not through the built-in tool: Bedrock Web Search supports OpenAI's GPT-5.4 and later models only, so a Claude, Nova or Llama model cannot call it directly. But you can still give Claude current information by handing it your own search_web tool through the Converse API's client-side tool use, and answering that tool with a Web Search call on a supported GPT model. Claude decides when to search; your code does the searching; the citations come back as text Claude can quote.

The Claude side, with boto3's Converse API on bedrock-runtime:

import boto3

rt = boto3.client("bedrock-runtime", region_name="us-west-2")
TOOLS = {"tools": [{"toolSpec": {
    "name": "search_web",
    "description": "Search the public web for current information and return a short answer with source links.",
    "inputSchema": {"json": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}}]}

def ask(model_id, question):
    msgs = [{"role": "user", "content": [{"text": question}]}]
    while True:
        r = rt.converse(modelId=model_id, messages=msgs, toolConfig=TOOLS)
        out = r["output"]["message"]
        msgs.append(out)                                  # keep the whole assistant message
        if r["stopReason"] != "tool_use":
            return out["content"][0]["text"]
        msgs.append({"role": "user", "content": [
            {"toolResult": {"toolUseId": b["toolUse"]["toolUseId"],
                            "content": [{"text": search_web(b["toolUse"]["input"]["query"])}]}}
            for b in out["content"] if "toolUse" in b]})

And the search side, which calls Web Search on Mantle with a GPT model and returns the answer plus its sources as plain text:

from openai import OpenAI
mantle = OpenAI()   # OPENAI_API_KEY + OPENAI_BASE_URL pointing at bedrock-mantle

def search_web(query):
    r = mantle.responses.create(
        model="openai.gpt-5.6-terra",
        input=f"Answer briefly with facts and dates: {query}",
        tools=[{"type": "web_search", "external_web_access": False, "search_context_size": "low"}],
    )
    links = [f"{a.title}: {a.url}" for item in r.output for part in (getattr(item, "content", None) or [])
             for a in (getattr(part, "annotations", None) or []) if a.type == "url_citation"]
    return r.output_text + "\nSources:\n" + "\n".join(links)

Both request shapes were checked against botocore's own Converse API model, through two full turns: the tool request and the tool result. You pay twice for each search, once for Claude's tokens and once for the GPT call plus the $0.012 query fee, so keep the search side on low context and a short answer. Use your Claude model's inference profile ID for model_id. If you would rather not involve a second model, the same search_web function can call any search API you already pay for.

Web Search vs Knowledge Bases vs your own search tool

Web Search is one of three ways to ground a Bedrock model in information it was not trained on:

• Web Search for public, changing information: news, prices, release notes, documentation. No setup beyond permissions, but limited to GPT-5.4+ models on Mantle.
• Knowledge Bases for your own documents: manuals, policies, tickets. You load and sync the data, and it works with many Bedrock models.
• Your own tool, through client-side tool use, for anything else: a private API, a database, a search engine you already pay for, or any model that Web Search does not support.

They combine well. Jake's price checker uses Web Search for supplier prices and a small Knowledge Base for his own stock list, so it can answer "do we have it, and is it cheaper to reorder or to buy locally?" in one reply.

Bedrock Web Search vs OpenAI's own web search tool

If you have used web search in OpenAI's API, the Bedrock version will feel familiar on purpose: the same Responses API, the same {"type": "web_search"} tool, the same url_citation annotations, and the same external_web_access parameter with the same default, so code moves between the two with a base URL and a model ID change. The differences are about where things run and who controls them:

• The index: on Bedrock, Search uses a web index built and run by Amazon (public web content, licensed content and the Amazon Knowledge Graph), and your queries are not sent to a third-party search provider.
• Permissions: on Bedrock every search and fetch is an IAM-checked action under bedrock-websearch, which is how the silent-failure trap arises, and also how an administrator can turn the tool off with one SCP.
• Location of data: Bedrock processes Web Search strictly in-Region, and with external_web_access: false nothing leaves the AWS boundary.
• Auditing: CloudTrail data events record each call, without the query text.
• Billing: on your AWS bill, at $12.00 per 1,000 queries, alongside the model tokens and any committed-use or credits you have with AWS.

For a company already on AWS, those differences are usually the reason to use the Bedrock version: same developer experience, inside the account boundary its security team already manages.

A five-minute test before you ship

1. Confirm the Region and endpoint: your base URL is https://bedrock-mantle.REGION.api.aws/openai/v1 in us-east-1, us-east-2 or us-west-2.
2. Confirm the model is a GPT-5.4 or later ID, such as openai.gpt-5.6-terra.
3. Set external_web_access explicitly in every request, false unless you have granted ExternalWebAccess on purpose.
4. Turn on CloudTrail data events for Web Search in a test account, run one question that needs a page read ("Summarize the changes listed at" plus a release-notes URL), and check that the InvokeFetch event shows fetchedSources, not AccessDenied.
5. Check your filters by asking a question whose best answer lives outside your allowed domains: the answer should say it could not find it there.
6. Read the citations in the response and open two of them. If the answer claims things the pages do not say, tighten the prompt before users see it.
7. Look at cost after a day: Web Search queries and model tokens, per project.

Troubleshooting Bedrock Web Search

The answer has citations, but it clearly did not read the pages

The silent-failure trap: external_web_access is at its default of true and the identity lacks ExternalWebAccess, so every Fetch was denied. Set the parameter to false, or grant the permission. Confirm in CloudTrail data events (AccessDenied on InvokeFetch).

Web Search does nothing on bedrock-runtime

It is a server-side tool available only on bedrock-mantle. Point the SDK at https://bedrock-mantle.REGION.api.aws/openai/v1 and use the Responses API.

The model never searches

The model decides when a question needs current information. Ask about something recent or specific, and check that you used a GPT-5.4 or later model; other model families do not support the tool.

user_location with country "UK" is rejected

country must be an assigned ISO 3166-1 alpha-2 code, and UK is not one. Use GB. XK is rejected for the same reason.

Results still include a blocked or unlisted site

Check that domains are written without http:// or https://, remember that subdomains match their parent, and note that filters apply to Search results, not to pages the model fetches by URL.

Access denied in a Region you expected to work

Web Search runs only in us-east-1, us-east-2, us-west-2 and us-gov-west-1, and a policy with aws:RequestedRegion or an organization SCP may deny it elsewhere.

The bill is higher than the query count suggests

Search results and fetched pages add input tokens to the model bill. Lower search_context_size, ask for shorter answers, and track spending per project.

Amazon Bedrock Web Search: frequently asked questions

A week later, Jake's morning hour was a 30-second message: today's screen prices at both suppliers, with links, and a note when one had dropped. Ethan kept the filter to the two supplier domains and the switch firmly at false. "Does it ever go and read random websites?" Jake asked. "Only the two I told it to," Ethan said, "and it can't send our data anywhere else." If your setup behaves differently from what this page describes, please tell us. Guides like this stay right because readers write in.

Revision note. Written October 24, 2026, the day after AWS added domain filtering and user location to Bedrock Web Search. "Trust, but verify," the old saying goes, and with web-grounded answers the verifying is CloudTrail.