Free relay
POST https://relay.agentsearchhq.com/v1/search with {"query": "...", "max_results": 1-5}. 25 free searches per IP in total, then pay per call. Small free trials of /v1/extract and /v1/render. Details: free web search API.
For agent builders · no key
Building your own agent, bot or workflow? Call AgentSearch over plain HTTP or the hosted MCP with no account or API key, and add one optional header, X-Agent-Client, so we can see which integrations to support. Free tier: 25 free searches per IP in total, then pay per call.
POST https://relay.agentsearchhq.com/v1/search with {"query": "...", "max_results": 1-5}. 25 free searches per IP in total, then pay per call. Small free trials of /v1/extract and /v1/render. Details: free web search API.
https://relay.agentsearchhq.com/mcp (Streamable HTTP, no auth). Same free tools and limits as the relay. One-click setup for Cursor, VS Code, Claude and ChatGPT: MCP page.
https://api.agentsearchhq.com/x402/v1/...: search $0.003, news $0.003, extract $0.002, search_and_read $0.005 per call in USDC on Base, no cap, settled only on success. See x402 docs and pricing.
Send X-Agent-Client: <your-agent-name>/<version> on every HTTP call, for example X-Agent-Client: my-research-bot/1.2.
Most calls today arrive untagged, so we can't tell which agents and frameworks people build with. The tag tells us what to support, document and fix first. It doesn't change your limits, price or results.
name/version, letters, digits and @ / . _ - only, up to 60 characters. Scoped names work too, e.g. @acme/research-agent/0.3. Keep the name stable across releases and bump the version.
Usage stats count only the tag name and major.minor version, in aggregate. Like other request headers, the tag also sits in short-lived server access logs used for security. Don't put personal data, user IDs, emails or keys in it.
Our packages (MCP server, n8n node, LangChain, LlamaIndex, CrewAI, OpenAI Agents, Vercel AI SDK) and the hosted MCP send their own tag. Add it yourself only for direct HTTP calls.
curl -s https://relay.agentsearchhq.com/v1/search \
-H 'content-type: application/json' \
-H 'X-Agent-Client: my-research-bot/1.2' \
-d '{"query":"x402 protocol","max_results":5}'import httpx
r = httpx.post(
"https://relay.agentsearchhq.com/v1/search",
json={"query": "x402 protocol", "max_results": 5},
headers={"x-agent-client": "my-research-bot/1.2"},
timeout=20,
)
data = r.json()
if r.status_code in (402, 429):
# free_allowance_used (402 = x402 terms) or a limit: don't retry; data["error"]["pay_now"] has the paid steps
raise SystemExit(data["error"]["message"])
if "free_quota" in data:
print(data["free_quota"]["message"]) # 5 or fewer free searches left
for hit in data["results"]:
print(hit["title"], hit["url"])const res = await fetch("https://relay.agentsearchhq.com/v1/search", {
method: "POST",
headers: {
"content-type": "application/json",
"x-agent-client": "my-research-bot/1.2",
},
body: JSON.stringify({ query: "x402 protocol", max_results: 5 }),
signal: AbortSignal.timeout(20_000), // allow ~15 s: a slow upstream can fall back
});
const data = await res.json();
if (res.status === 402 || res.status === 429) {
// Free allowance used up (402 = x402 terms) or a limit: stop retrying, follow data.error.pay_now
throw new Error(data.error.message);
}
if (data.free_quota) console.warn(data.free_quota.message); // 5 or fewer left
for (const hit of data.results) console.log(hit.title, hit.url);{
"mcpServers": {
"agentsearch": { "url": "https://relay.agentsearchhq.com/mcp" }
}
}curl -si https://api.agentsearchhq.com/x402/v1/search \
-H 'content-type: application/json' \
-H 'X-Agent-Client: my-research-bot/1.2' \
-d '{"query":"x402 protocol","max_results":5}'
# -> HTTP 402 with the PAYMENT-REQUIRED header (nothing charged).
# An x402 client signs the payment and retries; see /docs/x402When 5 or fewer free searches are left, a successful response gets an extra free_quota object (remaining, message, wallet_setup). Show it to your user or log it.
All 25 free searches for this IP are used. The relay answers HTTP 402 with standard x402 v2 terms (PAYMENT-REQUIRED header, $0.003 per search to https://api.agentsearchhq.com/x402/v1/search), so an x402 client can pay and retry automatically. The body has error.pay_now with copy-paste steps for paid calls. Waiting or retrying won't help, so stop retrying and switch to the x402 API (set up a wallet in about 2 minutes: wallet setup).
A 429 with a Retry-After header means shared free capacity or a trial limit was hit. Honour Retry-After; never loop on 429s.
Allow about 15 to 20 seconds per call: a slow search provider can fall back to another one before answering. A 400 means invalid input (for example a missing query) and does not use your free allowance.
No. It is optional and never used for auth or billing. It tells us which integrations call AgentSearch so we know what to support and document next.
Your agent or integration name and version, like my-research-bot/1.2. Use letters, digits and @ / . _ - only, up to 60 characters. Don't put personal data, keys or user IDs in it.
25 free searches per IP in total, then pay per call. The allowance is a total per IP, not per day, and does not reset.
The relay answers HTTP 402 Payment Required with error.code free_allowance_used: a standard x402 v2 reply (PAYMENT-REQUIRED header, search $0.003 USDC on Base, paid at https://api.agentsearchhq.com/x402/v1/search) plus an error.pay_now object with copy-paste steps. x402 clients can pay it automatically. Waiting or retrying unpaid does not help. (AgentSearch packages and the hosted MCP get the same error as HTTP 429.)
Web Search API · Web Extract API · Web Render API · Pricing · MCP server · Docs · agents.md · llms.txt