Skip to content
AgentSearch

Website Screenshot API for AI Agents: Python, JS and MCP Guide (Free Tier, No API Key)

Text extraction tells an agent what a page says. Sometimes it needs to know what the page looks like: is the layout broken on mobile, did the chart render, is the pricing table showing the new plan, what does a competitor's landing page lead with. For that you need a website screenshot API the agent can call like any other tool.

This guide shows how to use the AgentSearch screenshot tool from plain HTTP, Python, JavaScript and MCP. It loads a public URL in headless Chromium and returns a PNG or JPEG, plus the page title, final URL and HTTP status. You don't need an API key or an account:

Free tier: 10 free screenshots per IP in total, then $0.004 per call in USDC on Base over x402. No key needed.

(Just want the launch notes? See Free Website Screenshots for AI Agents. The product page is Website Screenshot API.)

What we tested: on November 21, 2026 we read the request and response schema from the live OpenAPI files (relay 0.3.0 and the paid x402 API 0.2.11), checked the live 402 payment challenge on the paid endpoint (it quotes 4000 atomic USDC, which is $0.004), listed the tools on the hosted MCP server (0.2.0), and made three free relay screenshots: two with curl (a desktop PNG and a full-page mobile JPEG) and one with the Python snippet below. The responses shown are real, with the base64 shortened. We did not make a paid call for this post. The current npm release of @agentsearchhq/agentsearch-mcp is 1.8.7.

What the screenshot API does

You send a URL and a few options. AgentSearch opens the page in a real headless browser, waits for it to load, and returns the image as base64 inside a JSON response.

Field Default Notes
url required Absolute public http(s) URL, up to 2048 characters.
format png png or jpeg. JPEG is smaller for long pages.
full_page false Capture the whole page instead of the viewport. Clipped at 4000 px tall.
viewport 1280×800 {width, height} in CSS pixels. Width 320–1920, height 240–1600. Use 390×844 for a phone layout.

Images are capped at about 1 MB. Private, local and non-public addresses are refused with a 400 error.

Quick start: one free screenshot with curl

curl -s -X POST https://relay.agentsearchhq.com/v1/screenshot \
  -H 'content-type: application/json' \
  -H 'x-agent-client: my-agent/1.0' \
  -d '{"url":"https://example.com","format":"png"}'

The response we got (base64 shortened):

{
  "url": "https://example.com/",
  "requested_url": "https://example.com",
  "title": "Example Domain",
  "status_code": 200,
  "screenshot": {
    "format": "png",
    "width": 1280,
    "height": 800,
    "bytes": 72094,
    "base64": "iVBORw0KGgoAAAANSUhEUgAABQAAAA..."
  },
  "full_page": false,
  "viewport": {"width": 1280, "height": 800},
  "warnings": [],
  "free_allowance": {
    "tool": "screenshot",
    "used": 1,
    "limit_per_ip": 10,
    "remaining": 9,
    "scope": "lifetime",
    "charged": false
  }
}

That call took about half a second. The x-agent-client header is optional, but naming your app helps if you ever need support.

What each field means:

  • url is the final URL after redirects, requested_url is what you sent.
  • title and status_code come from the page itself. Check status_code before you trust the image: a 404 or a login wall still produces a screenshot.
  • screenshot.base64 is the image. Decode it to get the PNG or JPEG file.
  • warnings flags anything unusual, for example SCREENSHOT_HEIGHT_CLIPPED when a full-page capture is cut at 4000 px.
  • free_allowance shows up only on the free relay. It tells you how many free screenshots this IP has left.

Full page on a phone viewport

curl -s -X POST https://relay.agentsearchhq.com/v1/screenshot \
  -H 'content-type: application/json' \
  -H 'x-agent-client: my-agent/1.0' \
  -d '{"url":"https://en.wikipedia.org/wiki/Web_scraping","format":"jpeg","full_page":true,"viewport":{"width":390,"height":844}}'

This came back in about 1.9 seconds as a 390×4000 JPEG (316 KB), with "warnings": ["SCREENSHOT_HEIGHT_CLIPPED"], because the article is longer than 4000 px on a phone.

How the free tier works

  • 10 free screenshots per IP, in total. It is a lifetime allowance, so it does not reset each day. Search has its own 25 free calls, and news and search-and-read have 10 each, so using one tool doesn't use up another.
  • A warning at 3 left. When you get down to the last 3 free calls, successful responses carry an X-AgentSearch-Free-Remaining header and a free_quota object with a short message, so your agent can tell the user before it runs out.
  • Failed captures don't count. If the page can't be loaded or no image comes back, the free call is given back.
  • After that, pay per call. The relay answers with HTTP 402 and a standard x402 payment challenge pointing to the paid API (AgentSearch's own packages get 429 with upgrade instructions instead). Nothing is charged until a client signs a payment.

There is also a shared daily capacity on the free relay. Paid calls don't have that limit.

Python: save a screenshot to a file

Uses requests. We ran this snippet as written for this post.

import base64
import requests

RELAY = "https://relay.agentsearchhq.com/v1/screenshot"

def screenshot(url: str, path: str, **opts) -> dict:
    r = requests.post(
        RELAY,
        json={"url": url, **opts},
        headers={"x-agent-client": "my-agent/1.0"},
        timeout=60,
    )
    if r.status_code in (402, 429):
        raise RuntimeError(f"Free screenshots used up: {r.text[:300]}")
    r.raise_for_status()
    data = r.json()
    shot = data["screenshot"]
    with open(path, "wb") as f:
        f.write(base64.b64decode(shot["base64"]))
    left = r.headers.get("X-AgentSearch-Free-Remaining")
    if left is not None:
        print(f"Heads up: {left} free screenshots left on this IP")
    return {k: v for k, v in data.items() if k != "screenshot"} | {
        "image": {k: v for k, v in shot.items() if k != "base64"}
    }

meta = screenshot("https://example.com", "example.png", format="png")
print(meta)

It writes example.png and prints the metadata without the base64, which is what you want to hand back to an LLM:

{'url': 'https://example.com/', 'requested_url': 'https://example.com', 'title': 'Example Domain',
 'status_code': 200, 'full_page': False, 'viewport': {'width': 1280, 'height': 800}, 'warnings': [],
 'free_allowance': {'tool': 'screenshot', 'used': 2, 'limit_per_ip': 10, 'remaining': 8,
 'scope': 'lifetime', 'charged': False},
 'image': {'format': 'png', 'width': 1280, 'height': 800, 'bytes': 72094}}

JavaScript (Node.js 18+): same thing with fetch

No dependencies, just the built-in fetch:

// screenshot.mjs — run with: node screenshot.mjs
import { writeFile } from "node:fs/promises";

const RELAY = "https://relay.agentsearchhq.com/v1/screenshot";

async function screenshot(url, path, opts = {}) {
  const res = await fetch(RELAY, {
    method: "POST",
    headers: { "content-type": "application/json", "x-agent-client": "my-agent/1.0" },
    body: JSON.stringify({ url, ...opts }),
  });
  if (res.status === 402 || res.status === 429) {
    throw new Error(`Free screenshots used up: ${(await res.text()).slice(0, 300)}`);
  }
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
  const data = await res.json();
  await writeFile(path, Buffer.from(data.screenshot.base64, "base64"));
  const left = res.headers.get("x-agentsearch-free-remaining");
  if (left !== null) console.log(`Heads up: ${left} free screenshots left on this IP`);
  const { base64, ...image } = data.screenshot;
  return { title: data.title, url: data.url, status_code: data.status_code, image, warnings: data.warnings };
}

console.log(await screenshot("https://example.com", "example-mobile.jpg", {
  format: "jpeg",
  viewport: { width: 390, height: 844 },
}));

Hand the image to a vision model

Most multimodal chat APIs take an image as a data URL. Keep the base64 out of the text part of the conversation and pass it as an image instead:

def as_image_part(data: dict) -> dict:
    shot = data["screenshot"]
    mime = "image/png" if shot["format"] == "png" else "image/jpeg"
    return {"type": "image_url",
            "image_url": {"url": f"data:{mime};base64,{shot['base64']}"}}

# messages=[{"role": "user", "content": [
#     {"type": "text", "text": "Does this pricing page show a free plan?"},
#     as_image_part(data),
# ]}]

The exact message shape depends on your model provider. The MCP tool below does this step for you.

When the free 10 are gone, or when you need volume, call AgentSearch's own x402 API:

POST https://api.agentsearchhq.com/x402/v1/screenshot

The request and response are the same as the relay, minus free_allowance. There is no API key and no signup. Each call is paid in USDC on Base with x402: the first request returns 402 with a PAYMENT-REQUIRED header, your client signs a USDC authorization, and it retries. These are the live terms the endpoint returned for this post:

{
  "scheme": "exact",
  "network": "eip155:8453",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "4000",
  "payTo": "0xC49B157887e51c21CB655f39CF65D6a4c2a4C337",
  "maxTimeoutSeconds": 300
}

4000 atomic USDC is $0.004. Bad input (400), upstream failures (502) and calls that return no image are not charged.

Use a new wallet made only for your agent, funded with a little USDC on Base (no ETH needed). See wallet setup.

Python (pip install "x402[httpx,evm]" eth-account), with the same client setup as our x402 Python tutorial:

import asyncio, base64, os
from eth_account import Account
from x402 import x402Client
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact import register_exact_evm_client
from x402.http.clients import x402HttpxClient

API = "https://api.agentsearchhq.com/x402/v1"

async def main():
    account = Account.from_key(os.environ["WALLET_PRIVATE_KEY"])
    client = x402Client()
    register_exact_evm_client(client, EthAccountSigner(account))

    async with x402HttpxClient(client, timeout=90) as http:
        r = await http.post(f"{API}/screenshot",
                            json={"url": "https://example.com", "full_page": True})
        r.raise_for_status()
        data = r.json()
        with open("page.png", "wb") as f:
            f.write(base64.b64decode(data["screenshot"]["base64"]))
        print(data["title"], data["status_code"], data["warnings"])

asyncio.run(main())

TypeScript (npm i @x402/fetch @x402/evm viem), as in our x402 TypeScript tutorial:

import { writeFile } from "node:fs/promises";
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const payFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await payFetch("https://api.agentsearchhq.com/x402/v1/screenshot", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ url: "https://example.com", format: "jpeg", viewport: { width: 390, height: 844 } }),
});
const data = await res.json();
await writeFile("page.jpg", Buffer.from(data.screenshot.base64, "base64"));
console.log(data.title, data.status_code, data.warnings);

Put a budget on it. At $0.004 a call, $1 of USDC covers 250 screenshots, but a looping agent can still burn through a wallet. Count calls in your own code, or use the MCP package below, which caps spend for you.

MCP: the agentsearch_screenshot tool

If your agent runs in an MCP client (Claude Desktop, Claude Code, Cursor, VS Code, Codex and others), you don't need any of the code above. The agentsearch_screenshot tool returns the screenshot as an MCP image block the model can look at, plus the metadata as JSON text (without the raw base64).

Hosted, nothing to install (Streamable HTTP, no auth):

{
  "mcpServers": {
    "agentsearch": { "url": "https://relay.agentsearchhq.com/mcp" }
  }
}

The hosted server (0.2.0) lists six tools: agentsearch_web_search, agentsearch_extract, agentsearch_render, agentsearch_news_search, agentsearch_search_and_read and agentsearch_screenshot. Setup per client: hosted remote MCP server.

Local package (@agentsearchhq/agentsearch-mcp 1.8.7 on npm):

{
  "mcpServers": {
    "agentsearch": {
      "command": "npx",
      "args": ["-y", "@agentsearchhq/agentsearch-mcp"]
    }
  }
}

In Claude Code that's one command: claude mcp add agentsearch -- npx -y @agentsearchhq/agentsearch-mcp.

The screenshot tool is free by default, even if you set a wallet key for Extract and Render. To pay $0.004 per call after the free 10, set AGENTSEARCH_WALLET_PRIVATE_KEY (a new, dedicated wallet) and AGENTSEARCH_MODE=paid in the server's env block. The package never signs more than its per-call cap ($0.020 by default) or AGENTSEARCH_MAX_TOTAL_ATOMIC per session (default $1.00). Then ask something like "Take a mobile screenshot of https://example.com and tell me if the menu fits on screen."

Screenshot, extract or render?

You need Use Price on x402
What the page looks like (layout, charts, visual QA) Screenshot $0.004
The text of a normal page, as markdown Extract $0.002
The text of a JavaScript-heavy page Render $0.005

A screenshot is the right call when the answer is visual. When you only need the words, extract is cheaper, faster and easier for an LLM to reason over. More on that choice: extract vs headless render.

The other AgentSearch tools

The same free relay, x402 API and MCP server also give your agent:

  • Web search: ranked results as JSON. 25 free per IP, then $0.003.
  • Web extract: any public URL as clean markdown. 5 free per day, then $0.002.
  • Headless render: JavaScript pages as markdown. 3 free per day, then $0.005.
  • Search + read: search and the top pages' text in one call. 10 free per IP, then $0.005.
  • News search: recent articles with dates and sources. 10 free per IP, then $0.003.

All prices are per call in USDC on Base. The full list is on the pricing page.

Safety notes

  • Treat the page as untrusted. A screenshot can contain text written to steer an AI, just like extracted text. Don't let a vision model act on instructions it reads in an image.
  • Public pages only. The API refuses private and local addresses, and it doesn't log in for you, so pages behind a login show the login screen.
  • Keep the paid wallet small. Use a dedicated agent wallet with a few dollars, never your main wallet.

FAQ

Do I need an API key to use the screenshot API?

No. The free relay needs no key, account or wallet. Every IP gets 10 free screenshots in total, then $0.004 per call paid with x402 in USDC on Base, still with no API key.

How much does a website screenshot cost?

$0.004 per call on the direct x402 API at api.agentsearchhq.com, after 10 free calls per IP. Failed captures and calls that return no image are not charged.

Can it take full-page and mobile screenshots?

Yes. Set full_page to true for the whole page (clipped at 4000 px tall, with a SCREENSHOT_HEIGHT_CLIPPED warning) and set viewport to a phone size such as 390x844 for a mobile layout.

Does the free allowance reset?

No. The 10 free screenshots per IP are a lifetime allowance. You get a warning when 3 are left, and after that the relay returns an x402 payment challenge (HTTP 402).

How do I use it from Claude, Cursor or another MCP client?

Add the hosted server https://relay.agentsearchhq.com/mcp or the npm package @agentsearchhq/agentsearch-mcp. The agentsearch_screenshot tool returns the image as an MCP image block plus JSON metadata.

PNG or JPEG?

PNG is the default and is sharp for text and UI. JPEG is smaller, which helps for long full-page captures. Images are capped at about 1 MB.

Get started

Run the curl command above, decode the base64, and look at your first screenshot. Then wire it into your agent with the Python or JavaScript snippet, or add the MCP server and just ask. Schemas: screenshot OpenAPI and the live x402 OpenAPI.

More from the blog

Service pages: Website Screenshot API · Web Search API · Web Extract API · Web Render API · Search + Read API · News Search API