Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- The direct API returns ranked web results for your application to process. Results include a text extract, with a title, URL and publication time when available.
- Direct calls use IAM only. The API fields searchQuery, publishedAfter and publishedBefore differ from the MCP fields query, from and to.
- Without maxResults, the API returns up to 25 results and the MCP tool up to 10. A date-only publishedBefore becomes midnight UTC at the start of that date.
- The API supports six commercial Regions, with a default quota of 10 requests per second per account per Region. AWS GovCloud (US-West) has the connector route instead.
When to call InvokeWebSearch directly
Use the AWS SDKs or AWS CLI to call InvokeWebSearch when your application, custom agent loop or data pipeline consumes search results directly. AWS announced general availability on November 10, and the developer guide says there are no dedicated resources to create or manage.
The response contains ranked web results from an Amazon-operated web index. Each result includes a page text extract; the title, URL and publication time are supplied when available. Your application still decides how to read sources and compose an answer.
Agents that discover and call tools through the Model Context Protocol (MCP) can continue using the Web Search Tool connector in AgentCore Gateway. If you need a finished answer in one call, check Web Answer separately for its capabilities, Regions and pricing.
Change authorization and fields when moving from MCP
Direct calls use the AgentCore data plane endpoint and AWS Identity and Access Management (IAM) authorization only. A Gateway can also authorize callers with a JSON Web Token (JWT); do not assume its JWT is the authorization mechanism for this API.
The API takes search text in searchQuery, while the MCP tool uses query. The API uses publishedAfter and publishedBefore for the time range; MCP uses from and to. Replacing the endpoint alone does not make an MCP request body an API request.
The API carries domain filters in each request. The connector can also apply target-level domain lists. Without maxResults, the API returns up to 25 results and the MCP tool up to 10. These are defaults, not a promise that every query produces that many results.
A date-only publishedBefore means midnight UTC
Both interfaces include their publication-time bounds, but they interpret a date-only upper bound differently. An MCP to date includes the entire day. The AWS SDKs and CLI send an API publishedBefore date as midnight Coordinated Universal Time (UTC) at the start of that day.
For a hypothetical example, publishedBefore set to 2026-11-10 is sent as 2026-11-10T00:00:00Z. A page published at 2026-11-10T12:00:00Z falls after that upper bound; sharing the same date does not put it inside the range. This illustrates time comparison, not an actual search result.
For a precise interval, convert your business time zone to UTC, use explicit date-times and check the inclusive bounds. Do not treat the API end date as the MCP whole-day condition.
Check six Regions and the request quota
The API is available in US East (N. Virginia), us-east-1; US East (Ohio), us-east-2; US West (Oregon), us-west-2; Asia Pacific (Sydney), ap-southeast-2; Asia Pacific (Tokyo), ap-northeast-1; and Europe (Ireland), eu-west-1. Check service availability and account permissions in the Region you will call.
The API is unavailable in AWS GovCloud (US-West). The developer guide directs callers there to the Web Search Tool connector. Do not apply the connector Region list to the direct API.
The default quota is 10 InvokeWebSearch requests per second per account in each Region. You can contact AWS Support to request an increase. A request is not approval; schedule calls against the quota actually granted to your account.
Understand the $7 per 1,000-query price
AWS lists Web Search at $7 per 1,000 search queries, billed per query submitted, with no minimum fees or upfront commitments. Direct API calls have no Gateway charges. Calls through Gateway still require accounting for the Gateway services your architecture uses.
For example, a hypothetical 10,000 submitted queries cost $70 at the search rate alone. This illustrates one charge, not an actual bill; model inference and other services you use may have separate charges.
The announcement also supports calls from a virtual private cloud (VPC) through AWS PrivateLink and logging requests as AWS CloudTrail data events. These are supported connectivity and logging capabilities, not a promise that the network, audit and agent architecture is free. Check the relevant service pricing separately when needed.
Check the integration in a clear order
Choose a supported Region and an IAM-authorized calling identity, then configure searchQuery, domain and publication-time filters, and maxResults as needed from the API documentation. Use a few queries without credentials or private records to inspect requests and responses, recording the actual Region, parameters and errors.
Handle missing titles, URLs or publication times without inventing source details. The developer guide requires retaining and displaying the source citations and links supplied with results. Check original sources for important information: search ranking alone does not establish that information is correct or complete.
Sources
Frequently Asked Questions
Do MCP target-level domain restrictions automatically follow the direct API?
The guide says the direct API carries its own per-request domain filters, while the connector can also apply target-level lists. Review the application domain policy and actual requests when migrating; do not assume an old Gateway target configuration automatically constrains the new API route.
Can changing proxies resolve AccessDenied?
First check the calling identity, IAM authorization and selected Region. A proxy cannot grant AWS permissions or make an unsupported Region supported. Investigate the network path separately when there is specific evidence of DNS, TLS or connection timeout failures.