# Screenshot API

> Take a screenshot of any public web page. Built for AI agents: one request, one image.

## Take a screenshot

GET https://localscreenshot.com/v1/screenshot?url=https://example.com
Header: Authorization: Bearer YOUR_API_KEY (the key never goes in the URL)

The response is the image. Add response=json to get a link to the image and the page details instead.
POST with a JSON body works the same way.

## Options

- url (string): The public http or https page to capture.
- country (string): Load the page from this country (ISO 3166-1 alpha-2 code, see /v1/countries). The response reports the country actually observed. If it cannot be obtained, the request fails and is not charged. Costs 2 credits instead of 1.
- viewport (string): Screen size as WIDTHxHEIGHT, for example 1440x900. Shortcut for viewport_width and viewport_height.
- viewport_width (integer): Width of the browser window, in pixels.
- viewport_height (integer): Height of the browser window, in pixels. With full_page, the image is taller than this.
- device_scale_factor (number): Pixel density. 2 gives a sharper, larger image.
- device (string): Capture as this device (screen size, pixel density, mobile browser). One of: desktop, desktop_hd, laptop, ipad, ipad_pro, ipad_mini, iphone_15, iphone_15_pro_max, iphone_se, pixel_8, galaxy_s24.
- orientation (string): Hold a phone or a tablet upright (portrait) or on its side (landscape). Needs a phone or tablet device. One of: portrait, landscape.
- full_page (boolean): Capture the whole scrollable page instead of the visible part.
- selector (string): Capture only the first element matching this CSS selector.
- format (string): File format. pdf saves the whole page as a document; it cannot be combined with selector or max_width. One of: png, jpeg, webp, pdf.
- quality (integer): Quality for jpeg and webp. Ignored for png and pdf.
- color_scheme (string): Ask the page for its light or dark theme. One of: light, dark.
- language (string): Browser language, for example fr or fr-FR. Without it, a screenshot from a country uses the main language of that country.
- timezone (string): Browser time zone, for example Europe/Paris. Without it, a screenshot from a country uses the main time zone of that country.
- user_agent (string): User-Agent the page receives. A preset (googlebot, googlebot_mobile) or your own string. Useful to compare what a site shows to a crawler and to a visitor. A site that checks the crawler's IP address is not fooled.
- wait_for (string): Wait until an element matching this CSS selector is visible.
- click_selector (string): Click this one element before the screenshot, to open a menu, a tab or a dialog. A CSS selector matching exactly one element: use it when you know the code of the page. One click, no typing. Costs 1 more credit. Not with pdf, not with click_text.
- click_text (string): Same click, pointed at by the text a visitor reads on the element, for example "Show all": use it when you do not know the code of the page. The whole text of exactly one visible button, tab or other clickable element, upper or lower case. Not a part of it, not a pattern. One click, no typing. Costs 1 more credit. Not with pdf, not with click_selector.
- delay_ms (integer): Extra wait before the capture, in milliseconds.
- hide_selectors (array): Hide every element matching these CSS selectors. In a URL, separate them with commas.
- disable_animations (boolean): Freeze animations and transitions.
- hide_sticky_elements (boolean): Hide headers, bars and buttons that stay fixed on screen.
- block_cookie_banners (boolean): Removes most cookie banners. A banner the filters do not know stays in the picture.
- block_ads (boolean): Block ads.
- block_chat_widgets (boolean): Hide chat bubbles.
- close_popups (boolean): Close pop-ups and newsletter overlays.
- max_width (integer): Scale the image down to this width. Useful to keep it small for a vision model.
- response (string): image returns the picture itself. json returns its link, the page details and the attestation. One of: image, json.
- async (boolean): Return an id right away instead of waiting. Read the result at /v1/screenshots/{id}.

## MCP server

For AI tools that speak the Model Context Protocol (Claude, Cursor, VS Code and others).
- Endpoint: https://api.localscreenshot.com/mcp (Streamable HTTP, POST)
- Authentication: the same API key, in the header "Authorization: Bearer YOUR_API_KEY"
- Example, Claude Code: claude mcp add --transport http localscreenshot https://api.localscreenshot.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
- Free endpoint, no key: https://api.localscreenshot.com/mcp/free answers initialize and tools/list, lists the countries and the prices, and can show a screenshot of an example page. It does not capture a page of your choice.
- Setup for each tool: https://localscreenshot.com/mcp

## Command line

A client for terminals, scripts and CI. Same API key, same credits.
- With npx: npx localscreenshot https://example.com
- With npm: npm install -g localscreenshot
- With pip: pip install localscreenshot
- With pipx: pipx run localscreenshot https://example.com
- With uv: uvx localscreenshot https://example.com
- Example: localscreenshot https://example.com --full-page --country BR -o shot.png
- Python package: https://pypi.org/project/localscreenshot/. npm package: https://www.npmjs.com/package/localscreenshot. Source, MIT license: https://github.com/Sambel/localscreenshot-cli
- Key: the LOCALSCREENSHOT_API_KEY environment variable, or "localscreenshot login". Never an argument.
- Other commands: localscreenshot countries, localscreenshot credits. Exit code 0 when done, 1 when the API refuses or the screenshot fails, 2 for wrong usage.
- Page: https://localscreenshot.com/cli
- Guide: https://docs.localscreenshot.com/cli.md

## Free tier, countries, prices

- 50 free credits every month, no card. A free account can send 10 requests a minute and run 2 screenshots at a time.
- Every account without a paid plan gets 50 free credits each calendar month (UTC), given the first time it is used that month. They do not carry over: what is left is gone on the 1st. After the month the account was created, its email address must be confirmed. GET /v1/credits shows it for an account, under "free_monthly".
- Countries: 227. A screenshot can be taken from any of them.
- Plans start at €19 a month for 2,000 credits. Credit packs start at €12, paid once, for 1,000 credits. Prices are before tax.
- Pricing: https://localscreenshot.com/pricing

## Your screenshots

- GET https://localscreenshot.com/v1/screenshots lists them, newest first. Use limit (1 to 100) and the next_cursor of the previous page.
- GET https://localscreenshot.com/v1/screenshots/{id} reads one.
- DELETE https://localscreenshot.com/v1/screenshots/{id} deletes one: the image is destroyed and its links stop working.

## Credits

- A screenshot costs 1 credit. From a chosen country it costs 2.
- A failed screenshot is not charged. The number of failed screenshots per day is limited.
- GET https://localscreenshot.com/v1/credits shows what is left.

## Errors

Errors are JSON: {"error": {"code", "message", "retryable"}}. Retry only when retryable is true, and wait for the Retry-After header when present.
Send an Idempotency-Key header to retry safely: the same key returns the same screenshot and is charged once.

## Limits

- Only public http and https pages. No login, no bot check solving, no paywall bypass.
- The country reported is the one observed when the page was loaded, never the one requested. If it cannot be obtained, the request fails.
- The attestation is a signed technical record, not legal proof.

## More

- Documentation: https://docs.localscreenshot.com/ (every page also as Markdown: add .md to its address)
- The whole documentation in one text: https://docs.localscreenshot.com/llms-full.txt
- Connect an AI tool, an assistant, an automation platform or an agent framework: https://docs.localscreenshot.com/coding-tools.md, https://docs.localscreenshot.com/assistants.md, https://docs.localscreenshot.com/automation.md, https://docs.localscreenshot.com/frameworks.md
- OpenAPI: https://localscreenshot.com/v1/openapi.json
- Countries: https://localscreenshot.com/v1/countries
- MCP server: https://api.localscreenshot.com/mcp (same API key, in the Authorization header). Setup: https://localscreenshot.com/mcp
- The API in one page: https://localscreenshot.com/api