AgentCore Web Search API: Setup, Filters and Pricing

Last updated: November 10, 2026

The Amazon Bedrock AgentCore Web Search API became generally available on November 10, 2026. One InvokeWebSearch call returns up to 25 ranked web results with text extracts, filtered by domain and publication time. It uses IAM, needs no resources to set up, costs $7 per 1,000 queries and runs in six AWS Regions.

What’s new
API compared with the Gateway connector
How to set up and make your first call
Request fields and filters
Pricing, Regions and quotas
Errors and retries
Workflows for agent builders
Limitations
Frequently asked questions
Sources

What’s new

Until now, Web Search on AgentCore was reachable only as an MCP tool through an AgentCore gateway. According to the AWS announcement, the new InvokeWebSearch API gives applications, custom agent loops and data pipelines the same search results with a single call and no resources to create.

Results come from the Amazon-operated web index behind Web Search on AgentCore. Each result always includes a text extract and may include title, url and publishedAt. You call it with the AWS SDKs or the AWS CLI, authorize with IAM, can reach it privately through AWS PrivateLink, and can log calls as AWS CloudTrail data events.

This is a raw search API. If you want a finished, cited answer instead of a list of results, see our AgentCore Web Answer guide.

API compared with the Gateway connector

The AgentCore Web Search developer guide lists how the new API differs from the Web Search Tool connector:

Area	InvokeWebSearch API	Web Search Tool connector (Gateway)
How you call it	Your code calls the AgentCore data plane endpoint	Agents call an MCP tool through a gateway
Authorization	IAM only	IAM or JSON Web Token (JWT)
Domain lists	Per-request domain filter	Per-request, plus hidden target-level lists
Search text field	`searchQuery`	`query`
Default results	Up to 25	Up to 10
Date range fields	`publishedAfter` / `publishedBefore`	`from` / `to`
Date without a time	`publishedBefore` means midnight UTC at the start of that day	`to` includes the whole day
GovCloud (US-West)	Not available	Available

AWS’s rule of thumb: use the API when your code consumes the results, and the connector when agents discover and call tools over MCP.

How to set up and make your first call

Update Boto3 or the AWS CLI. The getting started page says earlier versions do not include the InvokeWebSearch operation.
Pick a supported Region, such as us-east-1.
Grant your IAM principal bedrock-agentcore:InvokeWebSearch on arn:aws:bedrock-agentcore:<Region>:aws:tool/web-search.v1. The account field is the literal value aws, not your account ID. Use * for the Region to allow every Region.
Call the API with webSearchId set to web-search.v1 and a searchQuery. Those are the only required fields.
Read the results array, which is already in ranked order, and keep each result’s source link for display.

A minimal Python call, adapted from the AWS example:

import boto3

client = boto3.client("bedrock-agentcore", region_name="us-east-1")
response = client.invoke_web_search(
    webSearchId="web-search.v1",
    searchQuery="Amazon Bedrock AgentCore release announcements",
    maxResults=5,
    filters={
        "domainFilter": {"include": ["aws.amazon.com"]},
        "publishedDateFilter": {"publishedAfter": "2026-11-01T00:00:00Z"},
    },
)
for r in response["results"]:
    print(r.get("title"), r.get("url"), r.get("publishedAt"))

The CLI equivalent is aws bedrock-agentcore invoke-web-search --web-search-id web-search.v1 --search-query "..." --max-results 5, with filters passed as JSON in --filters.

Request fields and filters

The request and response reference sets these rules:

searchQuery: 1 to 200 characters.
maxResults: 1 to 25; omitted means up to 25. There is no pagination.
domainFilter: include, exclude or both, each with 1 to 100 domain names and no scheme or path. A root domain also matches its subdomains, so example.net covers docs.example.net.
publishedDateFilter: inclusive publishedAfter and publishedBefore timestamps in UTC. To include a whole day, use its last second, such as 2026-01-31T23:59:59Z.
Body: only searchQuery, maxResults and filters, up to 32 KiB. Any other top-level field is rejected.

Pricing, Regions and quotas

The AgentCore pricing page lists Web Search at $7 per 1,000 queries, billed per query, with no minimum fees or upfront commitments. AWS says the API costs the same as Web Search through AgentCore Gateway, with no gateway charges.

The API runs in US East (N. Virginia), US East (Ohio), US West (Oregon), Asia Pacific (Sydney), Asia Pacific (Tokyo) and Europe (Ireland). By default, each account can send 10 requests per second per Region; AWS Support can raise that per Region.

AWS also states that the Web Search Tool acceptable use terms apply, including keeping and displaying the source citations and links returned with each result.

Errors and retries

The troubleshooting page maps the main errors:

ValidationException (400): a rule above was broken, such as an empty query or publishedAfter later than publishedBefore. Fix and resend.
AccessDeniedException (403): missing permission on the tool ARN, or a deny in an IAM or VPC endpoint policy.
ResourceNotFoundException (404): webSearchId is not web-search.v1.
ThrottlingException (429) and InternalServerException (500): retry with exponential backoff.
ServiceUnavailableException (503): retry, waiting retryAfterSeconds when present.

Workflows for agent builders

Trusted-source fact checks: send the claim as searchQuery with domainFilter.include set to your approved domains, then pass the extracts to your model.
Release tracking: combine a vendor domain with publishedAfter set to the last run time in a scheduled pipeline to collect only new pages.
Custom agent loops: expose InvokeWebSearch as a function tool in your own harness, set maxResults low (for example 5) to control context size, and keep URLs for citations.
Private networks: create an interface VPC endpoint for com.amazonaws.region.bedrock-agentcore with private DNS so SDK calls stay off the internet without code changes.

If you are comparing search APIs, see our guides to the DeepSeek Search API and Perplexity Agent Ultra. For hosted agent harnesses that can call tools like this one, see the OpenAI Agents API guide, and for AWS’s coding agent, the Kiro Auto Approve guide.

Limitations

The API has no pagination, caps queries at 200 characters, authorizes with IAM only and is not offered in GovCloud. AWS does not publish details about index coverage or freshness, so test recall for your own domains before relying on it.

Frequently asked questions

What is the AgentCore Web Search API?

It is an AWS API, InvokeWebSearch, that searches the web from your own code and returns ranked results with a text extract and, when available, the page title, URL and publication time. AWS made it generally available on November 10, 2026.

How much does the AgentCore Web Search API cost?

AWS bills Web Search at $7 per 1,000 queries, the same rate as Web Search through AgentCore Gateway, with no gateway charges, no minimum fees and no upfront commitments.

Which AWS Regions support the Web Search API?

US East (N. Virginia), US East (Ohio), US West (Oregon), Asia Pacific (Sydney), Asia Pacific (Tokyo) and Europe (Ireland). The API is not available in AWS GovCloud (US-West), where AWS points you to the Web Search Tool connector instead.

How many results can one InvokeWebSearch call return?

Between 1 and 25, set with maxResults. If you leave it out, the API returns up to 25 results. It does not paginate, so each call returns a single ranked list that can be shorter than maxResults.

What is the default rate limit?

Each account can send up to 10 InvokeWebSearch requests per second in each Region by default. You can ask AWS Support for a higher quota per Region. Requests above the limit return a ThrottlingException (HTTP 429).

Should I use the API or the Web Search Tool connector?

AWS recommends the API when your own code consumes the results, and the Gateway connector when agents discover and call tools over MCP. The connector also supports JWT authorization and hidden target-level domain lists.

AgentCore Web Search API: Power-User Guide to InvokeWebSearch, Filters and Pricing

Contents