How we cut our build time in half
","viewport_width":1200,"viewport_height":630}' \
--output og.png
```
An access key is free: https://curlshot.com/register. Read more:
- [Open Graph images](https://curlshot.com/docs/guides/open-graph-images.md)
- [Signed links](https://curlshot.com/docs/signed-links.md)
- [Caching](https://curlshot.com/docs/caching.md)
## Questions
### What size should an Open Graph image be?
1200 by 630 pixels is the size that X, LinkedIn, Facebook and most chat apps show without cropping.
### How do I make one image per page automatically?
Keep one HTML template and fill in the title of each page before you send it to CurlShot. Each request returns the card for that page.
### Can I use a screenshot of the page itself as the image?
Yes. Send the address of the page instead of HTML, with the same window size, and the card is a screenshot of its first screen.
### Is the image rendered again every time someone shares the link?
Not with the cache switched on. The card is rendered once and repeat requests are served from storage, without counting against your allowance.
## Related
- [Website thumbnail](https://curlshot.com/tools/website-thumbnail.md): Make a thumbnail or preview image of any website from its address. For directories, link lists, portfolios and newsletters. Free to try, one request by API.
- [Screenshot API](https://curlshot.com/tools/screenshot-api.md): A screenshot API for developers. One HTTP request turns a URL, HTML or Markdown into a PNG, JPEG, WebP or PDF. Full page, devices, blocking, cache, MCP.
- [HTML to image](https://curlshot.com/tools/html-to-image.md): Render your own HTML, CSS or Markdown into an image or a PDF with one API request. For social cards, certificates, receipts and reports.
## Guides
- [Social preview image sizes: the OG cheat sheet](https://curlshot.com/blog/social-preview-image-sizes.md): Open Graph image sizes for Facebook, LinkedIn, WhatsApp, iMessage, Discord, Slack and Google Discover, drawn to scale, with the tags and the fixes.
---
Source: https://curlshot.com/tools/screenshot-behind-login
# Screenshot a page behind a login
> Screenshot dashboards, admin pages and staging sites that need a login. Send a session cookie or a header with the request and the page opens signed in.
To screenshot a page that needs a login, send the session cookie of a signed-in user with the CurlShot request. The browser sets the cookie before it opens the page, so the site treats it as that user and shows the page instead of the sign-in form. Sites that use a token take it as an HTTP header, and password-protected staging sites take an Authorization value.
Page for people: https://curlshot.com/tools/screenshot-behind-login
## How to screenshot a page behind a login in three steps
1. Sign in to the site as a user made for this, and copy its session cookie.
2. Send the address of the page with the cookie in the cookies field.
3. Save the screenshot of the signed-in page.
## Cookie, header or password: which one to send
How you get past the sign-in depends on how the site remembers a signed-in user. Each way has its own option.
| The site signs you in with | Option | Example value |
| --- | --- | --- |
| A session cookie (most web apps) | cookies | session=YOUR_SESSION_COOKIE; Domain=example.com; Secure |
| A bearer token or an API key header | headers | X-Api-Key: YOUR_TOKEN |
| HTTP basic auth (staging sites) | authorization | Basic dXNlcjpwYXNz |
| A button that must be pressed first | click | #accept-terms |
- Credentials go only to the site you capture. authorization, and headers that carry a credential such as Cookie, Authorization or a name with token or key in it, are sent only to the origin of your url, not to other hosts the page loads files from or redirects to.
- Use POST, so the cookie is in the request body and not in an address that could end up in a log.
- Use an account made for screenshots, with read-only access.
## What people use it for
- Dashboards and reports as an image in a weekly email
- Screenshots of your own app for docs and release notes
- Staging and preview sites behind a password
- Admin pages, for a record of how they looked
## The same thing with the API
```bash
curl -X POST "https://curlshot.com/api/v1/screenshot" \
-H "X-Access-Key: YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/dashboard","cookies":["session=YOUR_SESSION_COOKIE; Domain=example.com; Secure"]}' \
--output dashboard.png
```
An access key is free: https://curlshot.com/register. Read more:
- [Screenshot a page behind a login](https://curlshot.com/docs/guides/screenshot-behind-login.md)
- [Customize the page](https://curlshot.com/docs/customize.md)
## Questions
### How do I take a screenshot of a page that requires login?
Send the session cookie of a signed-in user in the cookies field of a CurlShot request. The page then opens as that user.
### What if the site uses a token and not a cookie?
Send it with the headers option, as a named HTTP header. For HTTP basic authentication use the authorization option.
### Which account should I use?
One made for screenshots, with read-only access to the pages you need and nothing else. Send the request with POST so the cookie is in the body and not in a web address.
### Can it click through a sign-in form?
A cookie or a header is the reliable way. The click option presses one element before the screenshot and scripts runs your own JavaScript on the page, for a step such as closing a dialog.
## Related
- [Full-page screenshot](https://curlshot.com/tools/full-page-screenshot.md): Take a screenshot of a whole web page, from the top to the very bottom, as one image. Paste the address, nothing to install. Also available as an API.
- [Screenshot API](https://curlshot.com/tools/screenshot-api.md): A screenshot API for developers. One HTTP request turns a URL, HTML or Markdown into a PNG, JPEG, WebP or PDF. Full page, devices, blocking, cache, MCP.
- [Element screenshot](https://curlshot.com/tools/element-screenshot.md): Capture one part of a web page instead of all of it: a chart, a pricing table, a card. Name the element with a CSS selector and get an image of it alone.
---
Source: https://curlshot.com/tools/bulk-screenshots
# Screenshot a list of URLs at once
> Screenshot a whole list of web pages at once. Start up to 100 screenshots with one API call, then collect the results by webhook or one status request.
To screenshot many web pages at once, send the list to the CurlShot bulk endpoint: up to 100 requests in one call, each with its own options, on plans that include bulk. You get an answer at once with one job per page. The screenshots are made in the background, and you collect them with one status request for the whole batch or receive each one by webhook as it finishes.
Page for people: https://curlshot.com/tools/bulk-screenshots
## How to screenshot a list of URLs at once in three steps
1. Create an account on a plan that includes bulk, and copy your access key.
2. Send the list of addresses in one POST request to the bulk endpoint.
3. Follow the batch with one status request, or receive each result by webhook.
## One call, up to 100 pages
A bulk call is a list of normal requests sent together. Each item has its own options and becomes its own job, so one page can fail while the others succeed. The answer comes at once, with the jobs in the same order as your list.
| To collect the results | Use | Good when |
| --- | --- | --- |
| One status request for the whole batch | The batch_url in the answer | A script that runs, waits and moves on |
| A webhook for every finished job | webhook_url for the call, or one per item | A server that should react as soon as each file is ready |
- Every option of a single request works inside an item, written as JSON: "full_page": true, not "true".
- Each successful render counts as one screenshot. Failed renders are not counted.
- A longer list goes in several calls of up to 100.
Request:
```bash
curl -X POST "https://curlshot.com/api/v1/bulk" \
-H "X-Access-Key: YOUR_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{
"webhook_url": "https://your-app.example/hooks/screenshot",
"requests": [
{ "url": "https://example.com" },
{ "url": "https://en.wikipedia.org/wiki/Eiffel_Tower", "full_page": true, "format": "jpeg" },
{ "url": "https://news.ycombinator.com", "viewport_device": "iphone_15_pro" }
]
}'
```
## What people use it for
- Thumbnails for every site in a directory
- A screenshot of every page of a site before and after a redesign
- Nightly captures of a list of competitor or client pages
- PDF copies of a list of articles
## The same thing with the API
```bash
curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com&async=true&webhook_url=https://example.com/webhooks/screenshot" \
--output job.json
```
An access key is free: https://curlshot.com/register. Read more:
- [Bulk screenshots](https://curlshot.com/docs/bulk.md)
- [Async and webhooks](https://curlshot.com/docs/async-and-webhooks.md)
## Questions
### How do I take screenshots of multiple URLs at once?
Send them to the CurlShot bulk endpoint as one list. Each item is a normal request with its own address and options, and up to 100 fit in one call.
### How do I get the results?
Ask for the status of the batch, which lists every job and a link to each finished file, or give a webhook address and each result is sent to it when it is ready.
### What does the request on this page do?
It starts one screenshot in the background and sends the result to a webhook. A bulk call is a list of requests like it, started together.
### How is a batch counted?
Like the same screenshots made one by one: each successful render is one screenshot. Failed renders are not counted. The pricing page shows which plans include bulk calls.
## Related
- [Web page to PDF](https://curlshot.com/tools/website-to-pdf.md): Turn a web page into a PDF document from its address. Real pages, working links and selectable text. Paste the address, nothing to install. Also an API.
- [Website thumbnail](https://curlshot.com/tools/website-thumbnail.md): Make a thumbnail or preview image of any website from its address. For directories, link lists, portfolios and newsletters. Free to try, one request by API.
- [Screenshot API](https://curlshot.com/tools/screenshot-api.md): A screenshot API for developers. One HTTP request turns a URL, HTML or Markdown into a PNG, JPEG, WebP or PDF. Full page, devices, blocking, cache, MCP.
---
Source: https://curlshot.com/tools/screenshot-tool-for-ai-agents
# Let an AI agent see a web page
> Let an AI agent look at any web page. An MCP server with a take_screenshot tool, an OpenAPI description and llms.txt, or one plain HTTP request.
To let an AI agent see a web page, connect it to the CurlShot MCP server. The agent gets a take_screenshot tool: it passes the address of a page and receives a screenshot of it, which a model that reads images can look at. Agents without MCP use the same thing as one HTTP request, described in an OpenAPI file and in llms.txt.
Page for people: https://curlshot.com/tools/screenshot-tool-for-ai-agents
## How to let an AI agent see a web page in three steps
1. Create a free account and copy your access key.
2. Add the MCP server to your agent, or give it the screenshot request.
3. Ask the agent to look at a page. It takes the screenshot itself.
## Three ways in, for any kind of agent
Pick the one your agent already speaks. All three use the same access key and the same options.
| Way in | Address | Best for |
| --- | --- | --- |
| MCP server | /api/mcp, with the tools take_screenshot and list_devices | Claude, Cursor and other MCP clients |
| OpenAPI description | /openapi.json | Agents and code generators that build a client from a spec |
| Plain HTTP and llms.txt | /llms.txt, and the screenshot request | Any agent that can fetch a URL |
- Create a separate access key for the agent, so you can revoke it without touching your other keys.
- Leave "Require signature" off for that key: calls through MCP are not signed.
MCP client configuration:
```json
{
"mcpServers": {
"screenshots": {
"type": "http",
"url": "https://curlshot.com/api/mcp",
"headers": { "Authorization": "Bearer YOUR_ACCESS_KEY" }
}
}
}
```
## What people use it for
- A coding agent that checks how the page it just changed looks
- Research agents that read pages which need a real browser to load
- Visual checks: is the banner there, did the layout break
- Reports with screenshots, written by an assistant
## The same thing with the API
```bash
curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com&response_type=json&image_width=1200" \
--output screenshot.json
```
An access key is free: https://curlshot.com/register. Read more:
- [For AI agents](https://curlshot.com/docs/guides/ai-agents.md)
- [Getting started](https://curlshot.com/docs/getting-started.md)
## Questions
### How can an AI agent take a screenshot of a website?
Through the CurlShot MCP server, which gives the agent a take_screenshot tool, or with one HTTP request that returns the image.
### What does the agent get back?
The image itself, or with response_type=json a short JSON answer with a link to the file, which is easier for a tool call to pass on.
### Can the agent read the page as text too?
The service returns images and PDFs. A PDF of a page has text that can be selected and extracted, and a model that reads images can read a screenshot directly.
### How do I keep the cost of an agent under control?
Each plan is a fixed number of screenshots a month, and an access key can be revoked at any time. Repeat requests for the same page can come from the cache at no cost.
## Related
- [Full-page screenshot](https://curlshot.com/tools/full-page-screenshot.md): Take a screenshot of a whole web page, from the top to the very bottom, as one image. Paste the address, nothing to install. Also available as an API.
- [Screenshot API](https://curlshot.com/tools/screenshot-api.md): A screenshot API for developers. One HTTP request turns a URL, HTML or Markdown into a PNG, JPEG, WebP or PDF. Full page, devices, blocking, cache, MCP.
- [HTML to image](https://curlshot.com/tools/html-to-image.md): Render your own HTML, CSS or Markdown into an image or a PDF with one API request. For social cards, certificates, receipts and reports.
## Guides
- [Screenshots for AI agents: let a model see a page](https://curlshot.com/blog/screenshots-for-ai-agents.md): When to give an AI agent a screenshot, HTML, markdown or the accessibility tree, what a screenshot costs in tokens on each vendor, and how to wire it up.
---
Source: https://curlshot.com/pricing
# CurlShot pricing
Each plan is a fixed number of screenshots a month for a fixed price. Nothing is charged on top unless you turn on overage.
| Plan | Price per month | Screenshots per month | Requests per minute | Renders at once |
| --- | --- | --- | --- | --- |
| Free | Free | 100 | 10 | 1 |
| Starter | $19 | 3,000 | 60 | 5 |
| Growth | $79 | 15,000 | 150 | 15 |
| Scale | $249 | 60,000 | 400 | 40 |
Optional overage on paid plans, off by default: Starter $8, Growth $5, Scale $4 per extra 1,000. It is paid from a prepaid balance and stops at a monthly cap the account owner sets; at the cap, requests answer 402.
## What counts
- One successful render is one screenshot, whatever its size: a full-page capture of a long article counts the same as a thumbnail.
- Failed renders are not counted.
- Cache hits are not counted: a screenshot served again from the cache is free.
- The tool on the home page works without an account.
## Refunds
- 14-day money-back guarantee: the first payment of an account is refunded in full on request within 14 days; the plan then ends. Renewals are not refunded. Policy: https://curlshot.com/refunds
## Limits next to the monthly number
- Requests per minute and renders at once, as in the table.
- A maximum height and pixel density for full-page captures, which is lower on the free plan. `GET /usage` reports the values of an account.
Start free, no card: https://curlshot.com/register. Page for people: https://curlshot.com/pricing. Details: https://curlshot.com/docs/usage-and-limits.md
---
Source: https://curlshot.com/
# CurlShot: questions and answers
## What is CurlShot?
CurlShot takes a screenshot of any web page. You give it the address of the page, it opens the page the way a normal browser would, and it hands you the screenshot as an image or a PDF.
## Do I need to install anything?
No. It works right on this page, in any browser, on a computer or a phone. There is nothing to download or set up.
## Is it free?
You can try it on this page without an account. A free account gives you 100 screenshots every month, and you do not need a card to sign up. If you need more, the paid plans have a fixed price each month.
## Can it take a screenshot of the whole page, not only the part I see on my screen?
Yes. Choose "Whole page" and the screenshot runs from the top of the page to the very bottom, including everything you would normally have to scroll to see.
## Can I get a PDF instead of an image?
Yes. Choose "PDF" and the page is laid out on paper-sized pages, ready to print, email or file.
## Can it hide cookie pop-ups and ads?
Yes, on most websites. Cookie pop-ups, ads and chat bubbles are removed before the screenshot is taken, so you get a clean page. It does not catch every one on every site.
## Why did my page not work?
CurlShot can open any page that anyone can visit without a password. Pages behind a login will show the login screen instead, and a few websites turn away visitors that are not people. Check the address for typos and try again.
## What counts as one screenshot?
One screenshot that worked. If a screenshot fails, it does not count. The free plan includes 100 screenshots every month.
## What happens when I use up my screenshots for the month?
It stops until the next month starts, or until you move to a bigger plan. Plans have a fixed monthly price, and nothing is charged on top unless you turn on overage on a paid plan, which stops at a monthly cap you set.
## Is there a screenshot API for developers?
Yes. One HTTP request returns a PNG, JPEG, WebP or PDF of a URL, or of HTML or Markdown you send. The browsers run on our side, so it works from any language and any server. Signed links let you put a screenshot URL straight into a web page without exposing your key.
## Can the API capture pages behind a login or on a private network?
It can capture a page behind a login when you send what the page needs: cookies, extra headers or an Authorization header. Local and private addresses are refused on purpose; for those, send the HTML directly and it is rendered the same way.
## Can AI agents use it?
Yes. There is an MCP server with a take_screenshot tool, an OpenAPI description, an llms.txt map, and a markdown version of every docs page.
## How do I screenshot an entire web page, not only the part I see?
Paste the page address into CurlShot and keep "Whole page" selected. The screenshot covers the page from the top to the bottom, including everything you would have to scroll to see.
## Do images further down the page appear in the screenshot?
Yes. Many pages load images only when you scroll to them. CurlShot scrolls through the page first so those images load, then takes the screenshot.
## Is there a limit to how tall the page can be?
Yes. Very long pages are cut off at a maximum height so the image stays a usable size. The limit is higher on paid plans, and with the API you set it yourself with the full_page_max_height option.
## How do I convert a URL to a PDF?
Paste the URL into CurlShot, choose PDF and press the button. Developers send one request: the screenshot address with format=pdf.
## Can I select and copy the text in the PDF?
Yes. The PDF is made by a real browser, the same way as its "Save as PDF", so the text stays text and links keep working.
## Can I choose the paper size?
With the API, yes: paper format, landscape, margins and whether backgrounds are printed are all options. There is also an option to fit the whole page on one long sheet.
## How do I convert a URL to a PNG or JPG?
Paste the URL into CurlShot and download the screenshot. With the API, add format=png, format=jpeg or format=webp to the request.
## Which image format should I pick?
PNG is exact and best for pages with text and flat colour. JPEG and WebP make much smaller files and are the better choice for long pages and photos.
## Can I get a smaller image, such as a thumbnail?
Yes. With the API, image_width and image_height resize the result, so you can ask for a 400 pixel wide thumbnail directly.
## How can I see what my website looks like on a phone?
Paste the address into CurlShot and choose Phone. You get a screenshot of the mobile version of the page, as a phone would show it.
## Which devices can I choose?
On this page: a phone, a tablet and a computer. The API has a list of named devices, including current iPhone, Pixel and iPad models and common laptop and desktop sizes, and you can also set any width and height yourself.
## Is this a real phone?
No. It is a real browser set up like the phone: the same screen size, pixel density, touch support and browser identity. That is what decides which layout a site serves, so the result matches what the phone shows for almost all sites.
## How do I take a screenshot without the cookie banner?
Use CurlShot with "Hide ads and cookie pop-ups" switched on. With the API, add block_cookie_banners=true to the request.
## Does it work on every website?
It works on most sites, not all. The common consent tools are covered. For a site with an unusual pop-up, the API can hide any element by its selector or click a button before the capture.
## Can it hide other things on the page?
Yes. The other blockers have their own switches, covered on the screenshot without ads page.
## How do I generate a thumbnail from a URL?
Paste the URL into CurlShot and choose "Just the top". With the API, add image_width to get the thumbnail at the size you need.
## Can I show the thumbnail directly in a web page?
Yes. The screenshot request is a normal web address, so it can be the source of an image. Use a signed link so your access key is not visible in the page.
## Do repeated views cost screenshots?
Not with the cache switched on. A cached screenshot is served again without counting against your allowance.
## What is a screenshot API?
A service that takes screenshots of web pages for your code. You send the address of a page, it opens the page in a browser on its own servers and returns the image, so you do not run or maintain headless browsers yourself.
## Which languages does it work with?
Any language that can fetch a URL. The docs have complete samples for cURL, Node.js, Python, PHP, Go and Ruby. There is nothing to install.
## How is usage counted?
One successful render is one screenshot, whatever its size. Failed renders and cache hits are not counted. Each plan is a fixed number of screenshots a month for a fixed price.
## Can an AI agent use it?
Yes. CurlShot has an MCP server with a take_screenshot tool, an OpenAPI description and an llms.txt file, so an agent can look at any web page.
## How do I convert HTML to an image?
Send the HTML to CurlShot in the html field of a POST request. The answer is the image file. Set viewport_width and viewport_height to the size the image should have.
## Can I use my own fonts and images?
Yes. The HTML is rendered like a web page, so fonts and images referenced by a public address load normally.
## Can I get a PDF instead?
Yes. Add format=pdf. Paper size, margins and orientation are options.
## Does it take Markdown?
Yes. Send a markdown field instead of html and it is rendered as a clean, styled page.
## How do I record a video of a website scrolling?
Send CurlShot the address of the page with format=mp4. The answer is the video file: the page from top to bottom, in a 1280 by 720 window. In the dashboard playground you do the same with a form and a button.
## Can I get a GIF instead of a video?
Yes. Ask for format=gif. A GIF is 640 pixels wide unless you set another width, and it is a much larger file than an MP4 of the same page.
## How long is the video?
As long as the page needs: a taller page gives a longer video, up to 30 seconds. Set video_duration to choose the length yourself, and the scroll speeds up or slows down to fit.
## Can I record the phone version of a site?
Yes. Add a device, for example viewport_device=iphone_15_pro, and you get a tall video of the mobile layout.
## Does a video cost more than a screenshot?
No. A video counts as one screenshot of your monthly allowance. Plans differ in how long a video may be, up to 30 seconds.
## How do I convert a web page to a JPG?
Paste the address of the page into CurlShot and press "Take the screenshot". The download is a JPG image of the page.
## Can I choose the quality of the JPG?
With the API, yes. image_quality takes a number from 1 to 100: a lower number makes a smaller file, a higher one a sharper image.
## JPG, PNG or WebP: which should I use?
JPG is the small, universal choice for pages with photos. PNG keeps text and flat colors perfectly sharp and can have a transparent background. WebP is the smallest of the three and is meant for use on websites.
## How do I take a screenshot of a website on an iPad without an iPad?
Paste the address into CurlShot and choose Tablet. The page is opened with the screen size and browser identity of a tablet, and you get a screenshot of what it shows.
## Can I get the landscape view?
With the API, yes. Add viewport_landscape=true and the tablet is turned on its side before the screenshot is taken.
## Which tablets are available?
The API has presets for the iPad, iPad mini, iPad Air, iPad Pro 11 and 13 inch, Galaxy Tab S9 and Pixel Tablet, listed with their sizes on this page. You can also set any screen width and height yourself.
## How do I take a screenshot of a website in dark mode?
Send a CurlShot request with dark_mode=true. The page is asked for its dark theme before the screenshot is taken.
## Can I also turn animations off?
Yes. reduced_motion=true asks the page to stop its animations, which gives the same screenshot every time.
## Can I combine it with a phone view or a full page?
Yes. dark_mode works together with every other option: device presets, full_page, element captures and PDF.
## How do I take a screenshot of a specific element?
Add selector to a CurlShot request with the CSS selector of the element. The image contains that element and nothing else.
## What if the element appears late?
Add wait_for_selector with the same selector. The screenshot is taken only after the element is visible.
## Can I capture an area by coordinates?
Yes. clip_x, clip_y, clip_width and clip_height cut out a rectangle of the page, measured in pixels from its top left corner.
## Can I hide things inside or around the element?
Yes. hide_selectors hides any elements you name, and styles adds your own CSS to the page before the screenshot.
## How do I take a high-resolution screenshot of a website?
Add device_scale_factor=2 to a CurlShot request. The image has twice the width and height in pixels, with the same layout.
## What is the difference from a wider browser window?
A wider window changes the layout: the page shows its large-screen design. A higher pixel density keeps the layout and draws it with more pixels, so it is sharper.
## Which format is best for sharp text?
PNG keeps every pixel as it was drawn. For smaller files use WebP or JPEG with image_quality set to 90 or more.
## Can I set the exact size of the image?
Yes. viewport_width and viewport_height set the size of the browser window, and image_width resizes the finished image.
## How do I screenshot a page without the ads?
Paste the address into CurlShot. Ad networks are blocked while the page loads, so the ads never appear in the screenshot.
## What is left where the ad was?
Usually an empty space the size of the ad, or nothing at all when the page closes the gap. The content of the page is not changed.
## Can I block something else on the page?
With the API, yes. block_requests blocks any address pattern you give, block_resources blocks whole kinds of files such as fonts or video, and hide_selectors hides any element.
## How do I convert HTML to PDF?
Send the HTML to CurlShot in the html field of a POST request and add format=pdf. The answer is the PDF file.
## Do backgrounds and colors print?
Yes. Background colors and images are printed unless you switch them off with pdf_print_background=false, for a document that saves ink.
## Can I control page breaks?
Yes, with normal CSS. Rules such as break-before, break-after and break-inside work as they do when a browser prints.
## Can the whole document be one long page?
Yes. pdf_fit_one_page puts everything on a single tall page with no breaks.
## How do I convert Markdown to PDF?
Send the Markdown to CurlShot in the markdown field of a POST request and add format=pdf. The answer is the PDF file.
## Can I change how it looks?
Yes. The styles option adds your own CSS to the page, so fonts, colors and spacing can match your brand.
## Can I get an image instead of a PDF?
Yes. Leave format out for a PNG, or ask for jpeg or webp. Set viewport_width to choose how wide the page is.
## Are tables and code blocks supported?
Yes. Tables, fenced code blocks, lists, links, quotes and images are all rendered.
## What size should an Open Graph image be?
1200 by 630 pixels is the size that X, LinkedIn, Facebook and most chat apps show without cropping.
## How do I make one image per page automatically?
Keep one HTML template and fill in the title of each page before you send it to CurlShot. Each request returns the card for that page.
## Can I use a screenshot of the page itself as the image?
Yes. Send the address of the page instead of HTML, with the same window size, and the card is a screenshot of its first screen.
## Is the image rendered again every time someone shares the link?
Not with the cache switched on. The card is rendered once and repeat requests are served from storage, without counting against your allowance.
## How do I take a screenshot of a page that requires login?
Send the session cookie of a signed-in user in the cookies field of a CurlShot request. The page then opens as that user.
## What if the site uses a token and not a cookie?
Send it with the headers option, as a named HTTP header. For HTTP basic authentication use the authorization option.
## Which account should I use?
One made for screenshots, with read-only access to the pages you need and nothing else. Send the request with POST so the cookie is in the body and not in a web address.
## Can it click through a sign-in form?
A cookie or a header is the reliable way. The click option presses one element before the screenshot and scripts runs your own JavaScript on the page, for a step such as closing a dialog.
## How do I take screenshots of multiple URLs at once?
Send them to the CurlShot bulk endpoint as one list. Each item is a normal request with its own address and options, and up to 100 fit in one call.
## How do I get the results?
Ask for the status of the batch, which lists every job and a link to each finished file, or give a webhook address and each result is sent to it when it is ready.
## What does the request on this page do?
It starts one screenshot in the background and sends the result to a webhook. A bulk call is a list of requests like it, started together.
## How is a batch counted?
Like the same screenshots made one by one: each successful render is one screenshot. Failed renders are not counted. The pricing page shows which plans include bulk calls.
## How can an AI agent take a screenshot of a website?
Through the CurlShot MCP server, which gives the agent a take_screenshot tool, or with one HTTP request that returns the image.
## What does the agent get back?
The image itself, or with response_type=json a short JSON answer with a link to the file, which is easier for a tool call to pass on.
## Can the agent read the page as text too?
The service returns images and PDFs. A PDF of a page has text that can be selected and extracted, and a model that reads images can read a screenshot directly.
## How do I keep the cost of an agent under control?
Each plan is a fixed number of screenshots a month, and an access key can be revoked at any time. Repeat requests for the same page can come from the cache at no cost.
---
Source: https://curlshot.com/docs/getting-started
# Getting started
Take your first screenshot in about a minute. Send one request with a page address and get an image back.
Paste this into a terminal. Swap `YOUR_ACCESS_KEY` for your own access key.
```bash
curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com" \
--output example.png
```
You get a file called `example.png`. It looks like this:
That is the whole idea of CurlShot. You send an address, you get back a screenshot of that page.
## Get your access key
An access key is a short code that tells us the request is yours. It is free to get one.
1. [Create an account](https://curlshot.com/register). You do not need a card.
2. Confirm your email address. The key does not work until you do.
3. Open **API keys** in the dashboard and copy the access key.
The free plan comes with a monthly quota of screenshots, so you can try everything in these docs without paying.
> **Tip**
>
> Treat your access key like a password and keep it on your server. To put a screenshot link in a web page, use a [signed link](https://curlshot.com/docs/signed-links.md). [Authentication and API keys](https://curlshot.com/docs/authentication.md) explains why.
## Take the screenshot from your code
The API is a normal web address, so anything that can fetch a URL can use it. Pick your language:
**cURL**
```bash
curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com" \
--output example.png
```
**Node.js**
```javascript
import { writeFile } from 'node:fs/promises'
const params = new URLSearchParams({
access_key: 'YOUR_ACCESS_KEY',
url: 'https://example.com',
})
const response = await fetch(`https://curlshot.com/api/v1/screenshot?${params}`)
if (!response.ok) throw new Error((await response.json()).error_message)
await writeFile('example.png', Buffer.from(await response.arrayBuffer()))
```
**Python**
```python
import requests
response = requests.get(
"https://curlshot.com/api/v1/screenshot",
params={"access_key": "YOUR_ACCESS_KEY", "url": "https://example.com"},
)
response.raise_for_status()
with open("example.png", "wb") as f:
f.write(response.content)
```
**PHP**
```php
'YOUR_ACCESS_KEY',
'url' => 'https://example.com',
]);
$image = file_get_contents("https://curlshot.com/api/v1/screenshot?$query");
file_put_contents('example.png', $image);
```
**Go**
```go
package main
import (
"io"
"net/http"
"net/url"
"os"
)
func main() {
params := url.Values{}
params.Set("access_key", "YOUR_ACCESS_KEY")
params.Set("url", "https://example.com")
resp, err := http.Get("https://curlshot.com/api/v1/screenshot?" + params.Encode())
if err != nil {
panic(err)
}
defer resp.Body.Close()
file, _ := os.Create("example.png")
defer file.Close()
io.Copy(file, resp.Body)
}
```
**Ruby**
```ruby
require "net/http"
uri = URI("https://curlshot.com/api/v1/screenshot")
uri.query = URI.encode_www_form(access_key: "YOUR_ACCESS_KEY", url: "https://example.com")
File.binwrite("example.png", Net::HTTP.get(uri))
```
Each sample does the same three things: builds the address, fetches it, and saves the bytes to a file.
## Change what you get
Everything else is an option: one more `name=value` pair in the address. Add an option, get a different screenshot.
This request captures the whole page as a JPEG, sized like an iPhone, with any cookie banner removed:
```bash
curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY\
&url=https://en.wikipedia.org/wiki/Eiffel_Tower\
&viewport_device=iphone_15_pro\
&full_page=true\
&block_cookie_banners=true\
&format=jpeg" \
--output eiffel.jpg
```
Here is what each option did:
| Option | What it changed |
| --- | --- |
| [`viewport_device`](https://curlshot.com/docs/devices.md) | The page was drawn on a phone-sized screen. |
| [`full_page`](https://curlshot.com/docs/full-page.md) | The capture runs to the bottom of the page, not just the first screen. |
| [`block_cookie_banners`](https://curlshot.com/docs/blocking.md) | A consent pop-up, if the page shows one, is hidden before the capture. |
| [`format`](https://curlshot.com/docs/options.md#format) | The file is a JPEG instead of a PNG. |
## When something goes wrong
A failed request never returns a broken image. It returns a short message in JSON, a text format for structured data, that says what happened.
This request leaves `https://` off the page address:
```bash
curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=example.com"
```
```json
{
"error_code": "invalid_options",
"error_message": "url: must be a full URL starting with http:// or https://",
"documentation_url": "https://curlshot.com/docs/errors#invalid_options",
"errors": [
{
"field": "url",
"message": "must be a full URL starting with http:// or https://"
}
]
}
```
`error_code` is a fixed word your code can check. `error_message` is written for you to read. The `errors` list comes with `invalid_options` only: it names each option that was refused.
Failed requests are not counted against your quota. The [errors page](https://curlshot.com/docs/errors.md) lists every code with its cause and its fix.
> **Common mistakes**
>
> - **The page address is cut off.** If it contains `&` or `?`, it must be encoded. See [The screenshot URL](https://curlshot.com/docs/screenshot-url.md#encode-the-url).
> - **You saved an error as a screenshot.** If the file will not open, look inside it: it probably holds the JSON error. Check the HTTP status before saving.
> - **A misspelled option.** Unknown options are refused, not ignored. The error message suggests the name you probably meant.
> - **The key is in your front-end code.** Anyone can read it there. Use a [signed link](https://curlshot.com/docs/signed-links.md).
## Where to go next
- [Authentication and API keys](https://curlshot.com/docs/authentication.md): the ways to send your key, and how to keep it safe.
- [The screenshot URL](https://curlshot.com/docs/screenshot-url.md): how the address is put together, and when to use POST.
- [Options reference](https://curlshot.com/docs/options.md): every option on one page.
- [Full-page screenshots](https://curlshot.com/docs/full-page.md), [Devices](https://curlshot.com/docs/devices.md) and [PDF rendering](https://curlshot.com/docs/pdf.md): the most common next steps.
- [Code examples](https://curlshot.com/docs/examples/node.md): longer samples for six languages.
---
Source: https://curlshot.com/docs/authentication
# Authentication and API keys
How to send your access key, what the secret key and signatures are for, and how to rotate, revoke and protect your keys.
Send your access key in a header, a named line that travels with the request, and the request is yours.
```bash
curl "https://curlshot.com/api/v1/screenshot?url=https://example.com" \
-H "X-Access-Key: YOUR_ACCESS_KEY" \
--output example.png
```
You get `example.png`, a screenshot of example.com. Without a key you get this instead:
```json
{
"error_code": "access_key_required",
"error_message": "An access key is required. Pass `access_key` or the `X-Access-Key` header.",
"documentation_url": "https://curlshot.com/docs/errors#access_key_required"
}
```
Every request to CurlShot needs an access key. It tells us whose quota, the monthly number of screenshots in your plan, the screenshot counts against.
## Where to find your key
1. [Create an account](https://curlshot.com/register), or [log in](https://curlshot.com/login).
2. Open **API keys** in the dashboard.
3. Copy the access key.
A key works once the email address of your account is confirmed. Until then, requests answer [`email_not_verified`](https://curlshot.com/docs/errors.md#email_not_verified).
You can have more than one key. Give each one a name, such as "production" or "staging", so you can tell them apart later.
## Three ways to send the key
All three do the same thing. Pick the one that fits your code.
| Where | What you send | Good for |
| --- | --- | --- |
| Query string | `access_key=YOUR_ACCESS_KEY` | Quick tests in a terminal. |
| Header | `X-Access-Key: YOUR_ACCESS_KEY` | Server code. The key stays out of the URL. |
| Header | `Authorization: Bearer YOUR_ACCESS_KEY` | HTTP clients and tools that already have a "bearer token" setting. |
If a request carries the key in more than one place, the query string wins.
Here is the header version in each language:
**cURL**
```bash
curl "https://curlshot.com/api/v1/screenshot?url=https://example.com" \
-H "X-Access-Key: YOUR_ACCESS_KEY" \
--output example.png
```
**Node.js**
```javascript
import { writeFile } from 'node:fs/promises'
const params = new URLSearchParams({ url: 'https://example.com' })
const response = await fetch(`https://curlshot.com/api/v1/screenshot?${params}`, {
headers: { 'X-Access-Key': process.env.SCREENSHOT_ACCESS_KEY },
})
if (!response.ok) throw new Error((await response.json()).error_message)
await writeFile('example.png', Buffer.from(await response.arrayBuffer()))
```
**Python**
```python
import os
import requests
response = requests.get(
"https://curlshot.com/api/v1/screenshot",
params={"url": "https://example.com"},
headers={"X-Access-Key": os.environ["SCREENSHOT_ACCESS_KEY"]},
)
response.raise_for_status()
with open("example.png", "wb") as f:
f.write(response.content)
```
**PHP**
```php
'https://example.com']);
$context = stream_context_create([
'http' => ['header' => 'X-Access-Key: ' . getenv('SCREENSHOT_ACCESS_KEY')],
]);
$image = file_get_contents("https://curlshot.com/api/v1/screenshot?$query", false, $context);
file_put_contents('example.png', $image);
```
**Go**
```go
package main
import (
"io"
"net/http"
"net/url"
"os"
)
func main() {
params := url.Values{}
params.Set("url", "https://example.com")
req, _ := http.NewRequest("GET", "https://curlshot.com/api/v1/screenshot?"+params.Encode(), nil)
req.Header.Set("X-Access-Key", os.Getenv("SCREENSHOT_ACCESS_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
file, _ := os.Create("example.png")
defer file.Close()
io.Copy(file, resp.Body)
}
```
**Ruby**
```ruby
require "net/http"
uri = URI("https://curlshot.com/api/v1/screenshot")
uri.query = URI.encode_www_form(url: "https://example.com")
request = Net::HTTP::Get.new(uri)
request["X-Access-Key"] = ENV["SCREENSHOT_ACCESS_KEY"]
response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
File.binwrite("example.png", response.body)
```
The samples read the key from an environment variable. That is a setting stored on your server, outside your code, so the key never ends up in your repository.
## Limits belong to the account, not the key
All your keys share one set of limits: the monthly quota, the number of requests per minute, and the number of renders that may run at the same time.
So a second key does not buy more requests per minute. Ten keys on one account have the same per-minute limit as one key.
Extra keys are for organisation and safety: one per app or environment, each one revocable on its own. [Usage and limits](https://curlshot.com/docs/usage-and-limits.md) explains the three limits.
## Access key and secret key
Each key you create is a pair: an access key and a secret key.
The **access key** identifies you. It travels with every request. Treat it like a password, even though it is the "public" half of the pair.
The **secret key** never travels. You use it on your own server to sign things, and we use our copy to check the signature. A signature is a short code computed from the request and the secret, so only someone who holds the secret can produce it.
You need the secret key in two places:
- [Signed links](https://curlshot.com/docs/signed-links.md), when a screenshot URL has to appear in a web page or an email.
- [Webhooks](https://curlshot.com/docs/async-and-webhooks.md), to check that a message really came from us.
If you only call the API from your server, you can ignore the secret key.
## Keep keys off the browser
Anything in a web page can be read by the person looking at it. That includes JavaScript files, HTML attributes and network requests.
So this is not safe in a public page:
```html