DEV Community: Grabbit

How to Capture a Webpage Screenshot Programmatically (URL to Image via API)

Nico Acosta — Mon, 27 Jul 2026 11:43:30 +0000

To capture a webpage screenshot from your code, send the page URL to a screenshot API and it returns a hosted image. One HTTP request in, one image URL out. The headless browser that renders the page runs in the cloud, so there is no Chromium to install and no browser process to keep alive.

That is the fast path. Below are the ways to capture a webpage, when each one fits, and how to get the full-page, format, and timing options right.

The quick answer

If you just want a URL captured as an image from your code, this is the whole thing:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "height": 720,
    "format": "webp"
  }'

The response is JSON with a hosted image_url:

{
  "id": "grb_01jx...",
  "status": "done",
  "target_url": "https://example.com",
  "image_url": "https://cdn.grabbit.live/grabs/grb_01jx....webp",
  "width": 1280,
  "height": 720,
  "format": "webp",
  "bytes": 62140,
  "execution_ms": 940,
  "created_at": "2026-07-27T09:00:00.000Z"
}

Store that image_url, embed it, or hand it to another service. The rest of this guide is about picking the right method and getting the capture right.

Manual versus programmatic capture

"Capture a webpage screenshot" splits into two different jobs, and the right tool depends on which one you have.

Manual, one page. You are looking at a page and want to save it. Your browser already does this. In Chrome or Edge, open the command menu with Ctrl+Shift+P (Cmd+Shift+P on Mac), type "screenshot," and choose "Capture full size screenshot" for the whole page. Edge has a dedicated shortcut: Ctrl+Shift+S, then "Capture full page." An extension like GoFullPage does the same through a toolbar button. For one page you are looking at right now, use one of these and move on.

Programmatic, repeatable. You need to capture pages from code, on a schedule, or across many URLs. The manual path falls apart here: you cannot click a browser menu inside a cron job, a CI pipeline, or a webhook handler. You need an endpoint you can call. That is the rest of this guide.

Capturing a webpage with an API

For anything repeatable, a screenshot API is the shortest path. You already saw the curl call. Here is the same capture in a few languages, since "how do I do this in my stack" is the real question.

Python, using requests:

import requests

resp = requests.post(
    "https://api.grabbit.live/v1/grabs",
    headers={"Authorization": "Bearer sk_live_..."},
    json={
        "url": "https://example.com",
        "width": 1280,
        "height": 720,
        "format": "webp",
    },
)
data = resp.json()
print(data["image_url"])

Node.js, using the built-in fetch:

const resp = await fetch('https://api.grabbit.live/v1/grabs', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    width: 1280,
    height: 720,
    format: 'webp',
  }),
});
const data = await resp.json();
console.log(data.image_url);

Every one of these is a plain HTTP call. No chromedriver, no 300 MB Chromium download, no async browser session to tear down. That is the whole reason to reach for an API over a local capture: the rendering machinery lives somewhere else.

Capturing the full page, not just the viewport

By default a capture stops at the viewport height you request. To grab the entire scrollable page as one tall image, set full_page to true:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "full_page": true,
    "format": "webp"
  }'

With full_page on, height is ignored and the render extends to the bottom of the document. This is the "scrolling screenshot" people ask for: everything below the fold, in one image. width must be between 320 and 1920 pixels; height, when you use it, between 240 and 1080.

Handling pages that load content late

The reason a real browser beats a raw-HTML fetch is that it runs JavaScript. Single-page apps, lazy-loaded images, and content that appears a beat after load all render the way they do for a visitor, because the capture happens in headless Chromium, not an HTML parser.

Two options control the timing:

delay_ms waits a fixed number of milliseconds (0 to 10000) after load before firing the capture. Use it when content animates or streams in.
selector waits for a specific element to appear and captures once it does. Use it when you know the exact node that signals "the page is ready."

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/dashboard",
    "width": 1440,
    "height": 900,
    "delay_ms": 1500,
    "format": "png"
  }'

This is also why an API can capture pages where a browser extension fails. A page can break extension-based capture with its layout, but a server that loads the URL like a normal visitor still gets a clean render of what the browser paints.

Choosing PNG, JPEG, or WebP

The format field takes png, jpeg, or webp, and picking wrong means either bloated files or lost quality.

WebP is the best default. For a typical webpage render it produces the smallest file at the same visual quality, which adds up fast when you store and serve thousands of captures. Use it unless you have a reason not to.
PNG is lossless and supports transparency. Reach for it when exact pixel fidelity matters, for example a baseline image in a visual regression test.
JPEG is the safest bet for older tooling that predates WebP. It is lossy, so text edges soften slightly.

Switching format is a one-word change in the request body, so you can experiment without rewriting anything.

When a local capture is the better call

An API is not always the answer. Capture locally instead when:

You are doing a single manual capture. Use the browser shortcut from earlier.
You already have the HTML, not a URL. If the markup lives in your app and is never served at an address, a local render avoids a round trip. See HTML to image for that pattern, including hosting your template at a URL and capturing it.
You cannot make outbound requests. In an air-gapped environment an API is off the table, so a bundled headless browser is the only option.

For everything else, especially anything on a schedule or in CI, the API path keeps your deployment small and removes a whole class of "it works locally but not in the container" failures.

Pricing is worth a word here because it is where these tools differ most. Grabbit charges a flat $0.002 per live capture as prepaid credits that never reset or expire monthly, so a batch that runs once a quarter does not forfeit an unused monthly allowance. That is different from the metered monthly quotas most screenshot tools bill on.

Next steps

The screenshot API covers the full parameter set, authentication, and rate limits. If you are wiring this into a job, the screenshot from a URL guide walks the request end to end, screenshot automation covers running captures on a schedule without a browser, and screenshot a list of URLs handles capturing many pages at once.

Originally published on the Grabbit blog.

How to Add a Screenshot Tool to Your AI Agent with MCP

Nico Acosta — Fri, 24 Jul 2026 11:41:38 +0000

An AI agent that writes frontend code has no way to see the result. It edits CSS, ships a component, and moves on, blind to whether the page actually renders correctly. The fix is to give the agent a tool that turns a URL into an image it can look at. Model Context Protocol (MCP) is the standard that makes wiring that tool a one-line job.

A screenshot MCP server exposes exactly one capability the agent was missing: send a URL, get back a rendered image. This walks through what a screenshot MCP server is, how to add a hosted one to Claude Code, Cursor, or any MCP host in a single command, and when a hosted server beats a self-hosted one that runs Chromium on your machine.

What a screenshot MCP server actually does

MCP is a protocol for connecting AI hosts to external tools. A host (Claude Code, Cursor, Claude Desktop, an agent framework) speaks MCP to a server, discovers the tools that server offers, and calls them mid-conversation. The agent never needs to know how the tool works internally, only its name, description, and inputs.

A screenshot MCP server offers a capture tool. The contract is simple:

The agent calls the tool with a URL (and optional width, format, and a few knobs).
The server renders the page in a real browser.
The server returns a hosted image, which the host passes back to the model as an image block.
The model looks at the pixels and reasons about them: spacing, overflow, a broken hero, a layout that only breaks at a real viewport.

That is the whole loop. What varies between servers is where the rendering happens. Some servers wrap a local Puppeteer or Playwright install and screenshot on your machine. A hosted server runs the browser on its own infrastructure, so there is nothing to install and nothing to keep alive.

Add a hosted screenshot MCP server in one command

Grabbit is a hosted screenshot MCP server at mcp.grabbit.live, spoken over Streamable HTTP. In Claude Code, adding it is one command plus a browser sign-in:

# Add Grabbit's hosted MCP server (Streamable HTTP)
claude mcp add --transport http grabbit https://mcp.grabbit.live

# Authenticate in your browser (no API key to paste):
#   /mcp   → select "grabbit" → Authenticate

That registers five tools with the host: grab (screenshot a URL), get_grab and list_grabs (fetch or browse past captures), get_usage (credits and plan), and get_pricing (an honest, dated comparison against ScreenshotOne, Urlbox, Browserless, and others). The agent can now call grab any time it needs to see a page.

Prefer a key over the OAuth flow? Pass a Bearer token as a header instead. A free test key (sk_test_...) returns placeholder renders at no cost, so you can prove the wiring before paying:

# Alternative: pass a key as a header instead of the OAuth flow.
claude mcp add --transport http grabbit https://mcp.grabbit.live \
  --header "Authorization: Bearer sk_test_..."

The same server works for any MCP host that speaks Streamable HTTP, not just Claude Code. Cursor, Claude Desktop, and agent frameworks point at the same https://mcp.grabbit.live endpoint and discover the same tools.

The see, fix, verify loop

The reason this matters shows up the moment an agent is doing visual work. Without a screenshot tool, a coding agent writes CSS and hopes. With one, it can close the loop:

You, in Claude Code:
  "Screenshot https://my-feature.preview.vercel.app and check the
   hero spacing against the mockup."

Claude calls the grab tool, looks at the returned image, edits the
CSS, then screenshots again to confirm the fix.

The agent captures the page it just shipped, looks at the rendered pixels, fixes what is off, and screenshots again to confirm. This is the same pattern practitioners keep landing on independently: give the agent a real rendered reference instead of asking it to reason about a page it cannot see. It generalizes past frontend work to visual QA after a deploy, verifying an OG card before a post goes live, or feeding a live competitor page into a vision step.

Because Grabbit captures public URLs and blocks localhost (SSRF protection is on by default), point the agent at a deployed preview or staging URL. That constraint is also what makes the loop work inside CI and remote runners: there is no local browser to drive, and the hosted render does not care.

When to self-host and when to use a hosted server

Search "screenshot MCP server" and most of the results are open-source repos that wrap Puppeteer or Playwright and run the capture locally. Those are a good fit when you want the browser on your own machine and are happy to maintain it. Be honest about what that maintenance is: a headless Chromium to install and patch, memory leaks to bound, fonts and locale to get right on Linux, and the same anti-bot walls a local browser hits on the open web.

A hosted screenshot MCP server removes that surface entirely. There is no Chromium in your environment, the render runs on infrastructure that already handles cookie and consent banners and JavaScript-heavy pages, and it works in sandboxes and CI where a local browser would have nothing to drive. The tradeoff is that you pay per capture instead of paying in devops time.

Grabbit's pricing is a flat $0.002 per live capture on the $50/year plan (25,000 captures), with prepaid credits that never reset or expire monthly, and test-environment captures are free. Browserless and Thum.io list a lower per-grab rate; Grabbit's edge is flat annual billing with no monthly-reset waste and the one-line MCP onboarding above. If your only need from a browser is a screenshot of a URL, a hosted server is the shorter path.

A screenshot server and a browser-automation server do different jobs

A screenshot MCP server is not a replacement for a browser-driving one. Playwright MCP gives an agent a real browser to click, type, and read the accessibility tree, which is what you want to walk through a login or a multi-step flow. A screenshot server has a narrower job: turn a URL into an image the agent can look at.

They pair naturally. The accessibility tree tells the agent what is on the page; a rendered screenshot shows it what the page looks like: visual bugs, CSS regressions, whether the thing actually looks right. Many agents use both. For the deeper pattern of feeding rendered images into a vision model, see Screenshots for AI Agents. To call the same capture from your own code without MCP, How to Screenshot a Website from a URL covers the plain HTTP path.

Calling the same capture over plain HTTP

MCP is the agent-native front door, but the same capture is one HTTP POST when you want it in a script, a cron job, or a framework tool you define by hand. This is what the grab MCP tool calls under the hood:

curl -X POST https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-feature.preview.vercel.app",
    "width": 1280,
    "height": 720,
    "format": "webp",
    "full_page": true,
    "delay_ms": 500
  }'

The response includes a hosted image_url you pass straight to a vision model as an image input. The knobs that matter most for agent work: full_page captures the whole document, delay_ms (0 to 10000) waits for late-loading content to settle, selector targets a single element by CSS selector, and format: "webp" keeps images small when you are passing them into a model. Width accepts 320 to 1920, height 240 to 1080.

Whether you wire it through MCP or call it directly, the point is the same: the agent stops working blind. It gets eyes on the web it is building.

For the full API reference, see the Grabbit screenshot API.

Originally published on the Grabbit blog.

How to Run Playwright in Docker (and the Browser-Deps Tax It Adds)

Nico Acosta — Thu, 23 Jul 2026 11:39:40 +0000

Playwright in Docker is mostly a solved problem, and the solution is one line: use the official image. The reason people end up here anyway is the failure mode underneath it. Playwright drives a real browser, a real browser links against dozens of native shared libraries, and slim container base images do not ship them. Miss one and you get a launch error that names a .so file instead of anything to do with your test.

This guide covers the working setup, the errors that actually show up in CI, and the honest boundary where containerizing a browser stops being worth it.

Use the official image

Microsoft publishes an image with the browsers and their system dependencies preinstalled:

mcr.microsoft.com/playwright:v1.61.1-noble

Pin the tag to the same Playwright version your project depends on. This is not a style preference. The npm package and the browser binaries are versioned together, and a mismatch produces a launch failure that reads like a corrupted install. If package.json says 1.61.1, the image tag says v1.61.1.

A working Dockerfile for a Node project:

FROM mcr.microsoft.com/playwright:v1.61.1-noble

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

CMD ["npx", "playwright", "test"]

Note what is missing: no playwright install, no install-deps, no apt-get block. The image already has the browsers and the libraries. What it does not have is your node_modules, which is why npm ci still runs. That distinction, the browsers are in the image but the package is in your project, is the thing the Stack Overflow threads keep circling.

Run it:

docker build -t my-tests .
docker run --rm --ipc=host my-tests

The --ipc=host flag is not optional in practice. Chromium uses shared memory heavily, Docker's default /dev/shm is 64MB, and the result is a browser that starts fine and then dies partway through a run. If you cannot use --ipc=host, use --shm-size=1gb instead.

Building your own image

Sometimes the official image does not fit: you need a specific base, a different runtime version, or a smaller final layer. Then you own the dependency problem, and the command that solves it is:

RUN npx playwright install --with-deps chromium

--with-deps is the important half. Without it you get the browser binary and none of the system libraries it dynamically links against, which is exactly the error people paste into forums: libnss3.so: cannot open shared object file. Naming a single browser (chromium) rather than installing all three cuts image size substantially when your suite only targets one.

Two things to know before you go this route. Alpine is not supported, because Playwright's browser builds link against glibc and Alpine ships musl, so start from a Debian or Ubuntu base. And installing browsers yourself adds a slow, network-dependent layer to every rebuild that the official image has already paid for.

The errors you will actually hit

The container exits immediately. Usually correct behavior rather than a bug: a container lives as long as PID 1, and if PID 1 is playwright test, the container stops when the run ends. Check the exit code before assuming it crashed. A non-zero code means the tests failed; zero means it worked and finished.

Browser closed unexpectedly, mid-run. Shared memory. Use --ipc=host or --shm-size=1gb.

A missing .so file at launch. Either a custom image without --with-deps, or an Alpine base.

Works locally, fails in CI. Nearly always a version mismatch between the image tag and the installed Playwright package after a dependency bump. Pin both, bump both together.

Screenshots differ between your machine and the container. This is expected, not broken. Font rendering and available font families differ across environments, so pixel comparisons made on a laptop will not match baselines made in a container. The fix is to generate baselines in the same container that verifies them, which is the main reason visual regression suites get containerized at all. There is more on that in visual regression testing in Playwright CI.

When Docker is the right call, and when it is not

Containerizing Playwright buys you a reproducible browser environment. That is worth real setup cost when your suite is doing browser work: navigating multi-step flows, logging in, filling forms, asserting on state, comparing screenshots against baselines that must be byte-stable. In those cases you need the whole browser under your control, and a container is how you make "the whole browser" identical everywhere.

The calculation changes when the browser is incidental. A large share of Playwright-in-Docker setups exist to produce an image of a page: an OG card, a report thumbnail, a nightly capture of a dashboard, a preview for a marketing site. There the container is not giving you determinism you need, it is giving you a browser you are obligated to maintain, so that an HTTP request can come back with a PNG.

If that is the job, the render can move off your infrastructure entirely:

curl -sS https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "width": 1280,
    "full_page": true,
    "delay_ms": 1000,
    "format": "webp"
  }'

The response carries an image_url pointing at the stored capture. No image to build, no browser version to pin, no --shm-size to remember, nothing to rebuild when a base image ships a new glibc.

The parameters map closely to what you would have written in Playwright: width (320 to 1920) pins the viewport the way setViewportSize does, full_page is the equivalent of fullPage: true, delay_ms (0 to 10000) replaces a fixed waitForTimeout after load, selector captures a single element the way a locator screenshot does, and format accepts png, jpeg, or webp.

The honest boundary: if the capture has to happen after a login, a click, or a form submission, none of this helps you and Playwright in a container is the correct tool. An API call renders a URL. It does not drive a session.

Cost, honestly

The relevant comparison is not per-request price against zero, because self-hosting is not free either. A containerized browser costs CI minutes on every build, image storage, and the recurring attention of whoever fixes it when a base image or Playwright version breaks the setup.

Grabbit is $0.002 per live grab, prepaid, with credits that do not reset monthly, which fits bursty work like a capture pipeline that runs hard some weeks and not at all in others. Test-environment keys return placeholder images at no cost, so you can wire the whole flow before any real capture runs. Other providers list lower per-grab rates, so if unit price is the only variable you care about, compare directly.

Where to go next

If you are keeping the container and just want the capture code to be right, how to take screenshots in Playwright covers the full-page, element, and CI cases. If you are weighing whether to keep running a browser at all, Puppeteer alternatives in 2026 walks the same decision from the other library, and the screenshot API page covers the hosted side in depth.

Originally published on the Grabbit blog.

Screenshot Automation: How to Capture Web Pages on a Schedule

Nico Acosta — Wed, 22 Jul 2026 11:40:28 +0000

Screenshot automation for web pages comes down to two pieces: something that fires on a schedule, and something that renders the page. You almost certainly already have the first piece. The second is where people get stuck, because the obvious answer, running headless Chromium yourself, means owning a browser fleet to produce a single image on a timer.

This guide covers the scheduled-capture pattern: how to wire a cron job to a screenshot API, how to pick an interval, how to keep captures consistent enough to compare, and where to store the results.

One clarification first, because search results for this topic mix two unrelated jobs. Capturing your own desktop or phone screen on a timer needs a local screen-capture utility. Capturing a web page on a timer, from a server, with no one at the keyboard, is what this post is about.

The pattern: scheduler plus render

Every scheduled screenshot setup has the same three stages:

Trigger. A cron entry, a GitHub Actions schedule, a Vercel or Cloudflare cron, or a workflow tool fires on an interval.
Render. One HTTP request per URL returns a hosted image.
Store. Write the image URL plus a timestamp somewhere you can query later.

The trigger is a solved problem in whatever stack you already run. The render stage is the only real decision, and it comes down to whether you run the browser or someone else does.

Running the browser yourself

The DIY version is a scheduled script that launches Chromium through Puppeteer or Playwright, navigates to the URL, calls page.screenshot(), and uploads the result. It works, and for a single URL on a laptop it is genuinely fine.

The cost shows up when it has to run unattended. A scheduled job means a long-lived environment, which means keeping the browser alive across runs or paying the launch cost every time. Serverless runtimes do not ship the native libraries Chromium expects, so you end up on @sparticuz/chromium or a custom container. Chromium leaks memory over long runs, so scheduled jobs that never restart eventually get killed. None of these are unsolvable, but they are all maintenance on infrastructure whose entire output is a PNG.

The honest rule: if your scheduled job needs to log in, click through a flow, or fill a form before the capture, you need your own browser automation and this maintenance is the price of the job. If it just needs to render a URL, you do not.

Running it as an API call

If the deliverable is a rendered image of a URL, the render stage collapses into one request. A cron entry, once a day at 6am:

0 6 * * * curl -sS https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "width": 1280,
    "full_page": true,
    "delay_ms": 1000,
    "format": "webp"
  }' >> /var/log/pricing-snapshots.log

The response includes an image_url pointing at the stored capture. That URL is the artifact: append it to a log, insert it into a table, post it to Slack. There is no browser on your side, nothing to keep alive between runs, and nothing to patch.

The parameters are the consistency controls, and they matter more in a scheduled pipeline than in a one-off capture:

width (320 to 1920) pins the viewport. Fix it and the layout is identical every run, so a diff shows real changes rather than reflow.
full_page captures the entire document instead of just the visible viewport, so a change below the fold is not invisible to your pipeline.
delay_ms (0 to 10000) waits after load for lazy-loaded images and animations to settle. This is the single most common fix for scheduled captures that look different every run for no reason.
format accepts png, jpeg, or webp. For an archive that accumulates one image per run, webp keeps storage down.
selector captures a single element instead of the page. Scoping a monitor to #pricing-table removes noise from unrelated sections of the page.

Scheduling more than one URL

Most real automations track a list, not a single page. Loop the list in the scheduled job and make one request per URL. Keep two things in mind:

Grabbit rate-limits to 60 requests per minute per team, so a list longer than about 60 URLs needs to be paced rather than fired in one burst. For a nightly job this is a non-issue; add a short sleep between calls and it stays well under.

Second, be deliberate about the identifier you store. A screenshot is only useful later if you can find it, so record the URL, the capture timestamp, and the returned image_url together. Overwriting a single "latest.png" throws away the history that made the automation worth building.

There is a fuller walkthrough of the batch case in how to screenshot a list of URLs.

Picking an interval

The interval should track how fast the content actually changes, not how often you would like to look at it:

What you are capturing	Reasonable interval
Your own app, for visual regressions	On every deploy, not a clock
Competitor pricing or marketing pages	Daily
News, dashboards, status pages	Hourly
Legal or compliance archiving	Daily, retained long term
A page that changes weekly at most	Weekly

Running more often than the page changes produces a pile of identical images and a bill that scales with nothing. The exception is your own application, where the right trigger is not a clock at all: capture on deploy, because that is the moment the page can change.

From automation to monitoring

A scheduled capture on its own is an archive. Add an image diff between consecutive captures and it becomes a monitor that tells you when something changed, which is usually the actual goal. pixelmatch handles strict pixel comparison and resemblejs does a more forgiving perceptual comparison for pages with anti-aliased text.

The consistency parameters above are what make that diff trustworthy. A pipeline with a floating viewport width or no settle delay will produce diffs on every run and you will stop reading the alerts within a week. Monitoring a website for visual changes covers the diff and alerting side in full.

Cost, honestly

Scheduled automation is the case where per-request pricing compounds, so it is worth doing the arithmetic before you set the interval. Grabbit is $0.002 per live grab. Fifty URLs captured daily is 1,500 grabs a month, or about $3. The same fifty URLs hourly is roughly 36,000 grabs a month, closer to $72. The interval, not the tool, is what drives the number.

Credits are prepaid and do not reset monthly, which suits scheduled work specifically: a job that runs unevenly, or that you pause for a quarter, does not forfeit anything at a billing boundary. Test-environment keys return placeholder images at no cost, so you can wire and debug the full schedule before any real capture runs. Other providers list lower per-grab rates, so if raw unit price is the only variable that matters to you, compare directly.

Where to go next

If you are building scheduled capture into a product, automated screenshots covers the API side in more depth. If you are starting from a single URL and have not automated anything yet, how to screenshot a website from a URL is the shorter starting point.

Originally published on the Grabbit blog.

How to Fix Puppeteer Memory Leaks in Production (and When to Stop Running Chromium)

Nico Acosta — Tue, 21 Jul 2026 11:40:18 +0000

If you run Puppeteer in production long enough, you eventually meet the same graph: resident memory climbing steadily over hours, flat under test, until a container hits its limit and the OOM killer takes it. The short version is that Puppeteer memory leaks in production are almost never a single bug. They are three problems stacked on top of each other, and the fix is a combination of hygiene, bounding, and an honest question about whether you should be running Chromium at all.

This post covers all three: what actually leaks, the fixes people ship (and keep shipping), how to find the real source instead of guessing, and the case for handing the whole thing off when your only job is a screenshot.

The short answer

Close everything. Every page and BrowserContext you open must be closed in a finally block, on every path including timeouts and throws. Leaked pages are leaked renderer processes.
Treat Chromium as disposable. A long-lived browser accumulates state it never fully releases. Recycle it after a fixed number of jobs instead of keeping one alive forever.
Bound the blast radius. Cap concurrency, launch with --disable-dev-shm-usage, and set a memory ceiling so one bad page cannot take the box down.
Reap zombies. Run under an init process (--init / tini) and force-kill on timeout so crashed captures do not leave orphaned Chromium behind.
Then ask if you need Chromium at all. If the deliverable is an image of a URL, a hosted screenshot API removes the fleet, and the memory problem with it.

The rest explains each one.

What actually leaks (it is not your Node heap)

The first mistake is measuring the wrong thing. You watch process.memoryUsage(), see the Node heap sitting calm, and conclude there is no leak. Meanwhile the container's memory keeps climbing. That gap is the whole story: Chromium runs as a tree of child processes, and the memory you are leaking lives in those children, not in your Node process.

Three things compound:

Unclosed pages and contexts. Every browser.newPage() and browser.createBrowserContext() spins up renderer state. If your handler throws or times out before it closes them, that state stays resident. Do this a few thousand times an hour and the leak is your own code path, not Chromium's.
A single long-lived browser accumulating state. The common "open one browser at startup, reuse it forever" pattern looks efficient and leaks slowly. Across thousands of navigations, Chromium holds onto caches, detached DOM nodes inside pages, and listeners it never fully frees. RSS drifts up even when you are closing pages correctly.
Zombie processes. A capture that crashes or hangs can leave an orphaned Chromium process the OS still counts against your cgroup. These do not show up in your app metrics at all. They show up as a box that is "out of memory" while your app swears it is using very little.

So the resident-set-size line you watch climb on your dashboard is usually the sum of leaked child processes and orphaned browsers, not a classic heap leak. That changes how you fix it.

Fix 1: close everything, in a finally block

The unglamorous fix that removes most of the leak. Wrap every capture so the page and browser are closed no matter how the function exits, including on a thrown error or a timeout:

async function capture(browser, url) {
  const page = await browser.newPage();
  try {
    await page.goto(url, { waitUntil: 'networkidle2', timeout: 30000 });
    return await page.screenshot({ fullPage: true });
  } finally {
    await page.close(); // runs on success, throw, and timeout alike
  }
}

The finally is the point. A lot of leaking code closes the page on the happy path and skips it whenever goto throws, which is exactly when captures pile up (a slow page, a network blip, a bot wall). Close in finally, and audit every early return and throw above it.

Fix 2: treat the browser as disposable

Even with perfect page hygiene, one browser held open for the life of the process drifts upward. The pattern teams converge on is a pooled browser that gets recycled after a fixed number of jobs:

let browser;
let jobs = 0;
const MAX_JOBS = 200; // recycle before the drift matters

async function getBrowser() {
  if (!browser || jobs >= MAX_JOBS) {
    if (browser) await browser.close();
    browser = await puppeteer.launch({
      args: ['--no-sandbox', '--disable-dev-shm-usage'],
    });
    jobs = 0;
  }
  jobs++;
  return browser;
}

You reuse the browser enough to amortize the several-hundred-millisecond startup cost, then throw it away before accumulated state becomes a problem. A brand-new browser per request is also leak-free but pays that cold start on every capture. Recycling is the middle path, and "disposable Chromium" is the reliability idea, not any single flag.

Fix 3: bound the blast radius

None of the launch flags below fix a leak. They stop one bad page from taking the whole container down:

--disable-dev-shm-usage makes Chromium use /tmp instead of the default /dev/shm, which is tiny (often 64MB) in containers and a frequent cause of crashes that turn into zombies.
--js-flags="--max-old-space-size=512" caps the V8 heap inside the renderer so a runaway page fails fast instead of eating the box.
Concurrency cap. Never run more parallel captures than the container has RAM for. A simple queue with a fixed worker count beats "spawn a browser per incoming request" every time. Each Chromium instance can easily want a few hundred MB, so on a 1GB container you are looking at a small handful of concurrent captures, not dozens.

Fix 4: reap the zombies

Orphaned Chromium processes are the leak that does not show up in your metrics. Two defenses:

Run under an init process. In Docker, pass --init, or use tini / dumb-init as PID 1. Without one, orphaned children are never reaped and accumulate until OOM.
Force-kill on timeout. Wrap the whole capture in an overall timeout that calls browser.close() (and, if that hangs, kills the process) so a stuck page cannot leave a browser resident forever.

Then watch for them: periodically log ps filtered to chrome so you can see the process count creeping before the OOM killer tells you the hard way.

How to actually find the source

Guessing is slow. Measure in this order:

Watch RSS and process count, not the Node heap. If total container RSS and the number of chrome processes climb while your Node heap is flat, the leak is unclosed pages, an un-recycled browser, or zombies. That alone narrows it to Fixes 1, 2, and 4.
Diff two heap snapshots under steady load. Take a snapshot of one browser context, run an hour of representative traffic, snapshot again, and diff. Detached DOM nodes and retained listeners that grow between snapshots point at page-level leaks in the site you are capturing (or in an page.on(...) handler you forgot to remove).
Confirm your finally blocks run. Add a counter for pages opened vs. pages closed. If they diverge, you found it before touching a profiler.

The DevTools heap profiler shows an OOM-killed container as "RSS growing over hours" rather than a single spike, which is why time-series RSS plus process count is the diagnostic that actually catches it.

When to stop running Chromium

Here is the honest part. Every fix above is real, and if you need a browser you should ship all of them. But notice what the work is: memory hygiene, process reaping, cold-start tuning, and a 3am pager rotation, all in service of keeping a browser fleet alive.

If the only reason you reached for Puppeteer is to take a screenshot of a URL, that is a lot of infrastructure for a job that is one HTTP request. A hosted screenshot API runs the browser for you and returns a hosted image, so there is no Chromium to launch, no pages to close, no zombies to reap, and no memory graph to watch:

curl -X POST https://grabbit.live/api/v1/grabs \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "full_page": true,
    "format": "webp"
  }'

The parameters map to the Puppeteer options you were already setting: width (320 to 1920), height (240 to 1080), full_page for the whole scroll height, format (png, jpeg, or webp), delay_ms (0 to 10000) to wait for late content, and selector to capture a single element. Grabbit is $0.002 per grab on prepaid credits that do not reset monthly, so you pay for the captures you run and nothing for a browser sitting idle. The Node.js screenshot guide shows the same request from fetch, and if you are wiring this into an agent, screenshots for AI agents covers that path.

This is not "never use Puppeteer." Keep the library when you click, type, scrape, or run end-to-end tests and genuinely need to drive the browser. For a broader take on that split, see Puppeteer alternatives by job. But when the deliverable is a picture of a page, handing the browser off is how the memory problem stops being your problem.

The takeaway

Puppeteer memory leaks in production are three problems wearing one trench coat: unclosed pages, an un-recycled browser, and zombie processes. Fix them with finally-block cleanup, disposable browser recycling, concurrency caps and bounding flags, and an init process that reaps orphans. Then measure RSS and process count, not just the Node heap, so you find the real source instead of guessing. And if screenshots are the whole job, the most durable fix is to not run Chromium at all.

Originally published on the Grabbit blog.

How to Convert a Webpage to an Image (URL to JPG, PNG, or WebP)

Nico Acosta — Mon, 20 Jul 2026 11:37:33 +0000

To convert a webpage to an image, send the page URL to a screenshot API and it returns a hosted JPG, PNG, or WebP. One HTTP request in, one image URL out. The headless browser that does the rendering runs in the cloud, so there is no converter to install and no local Chrome to babysit.

That is the fast path. Below are the approaches that work, when each one fits, and how to get the format, dimensions, and full-page options right.

The quick answer

If you just want a URL turned into an image from your code, this is the whole thing:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "height": 720,
    "format": "webp"
  }'

The response is JSON with a hosted image_url:

{
  "id": "grb_01jx...",
  "status": "done",
  "target_url": "https://example.com",
  "image_url": "https://cdn.grabbit.live/grabs/grb_01jx....webp",
  "width": 1280,
  "height": 720,
  "format": "webp",
  "bytes": 62140,
  "execution_ms": 940,
  "created_at": "2026-07-01T09:00:00.000Z"
}

Store that image_url, embed it, or hand it to another service. The rest of this guide is about picking the right tool and the right options.

Manual versus programmatic

"Convert a webpage to an image" splits into two very different jobs, and the right tool depends on which one you have.

Manual, one-off. You are looking at a page and want to save it as a JPG. Your browser already does this. In Chrome or Edge, open the command menu with Ctrl+Shift+P (Cmd+Shift+P on Mac), type "screenshot," and choose "Capture full size screenshot." No tool required. Free online converters like Web2PDF Convert or CloudConvert do the same thing through a form: paste a URL, download the image.

Programmatic, repeatable. You need to convert pages to images from code, on a schedule, or across many URLs. This is where the manual path falls apart: you cannot click a browser menu inside a cron job, a CI pipeline, or a webhook handler. You need an endpoint you can call.

This guide is about the second job. If you only need a one-off image, use the browser shortcut above and move on.

Converting a webpage to an image with an API

For anything repeatable, a screenshot API is the shortest path. You already saw the curl call. Here is the same request in a few languages, since "how do I do this in my stack" is the real question.

Python, using requests:

import requests

resp = requests.post(
    "https://api.grabbit.live/v1/grabs",
    headers={"Authorization": "Bearer sk_live_..."},
    json={
        "url": "https://example.com",
        "width": 1280,
        "height": 720,
        "format": "webp",
    },
)
data = resp.json()
print(data["image_url"])

Node.js, using the built-in fetch:

const resp = await fetch('https://api.grabbit.live/v1/grabs', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    width: 1280,
    height: 720,
    format: 'webp',
  }),
});
const data = await resp.json();
console.log(data.image_url);

Every one of these is a plain HTTP call. No chromedriver, no 300 MB Chromium download, no async browser session to tear down afterward. That is the whole reason to reach for an API over a local converter: the rendering machinery lives somewhere else.

Choosing PNG, JPEG, or WebP

The format field takes png, jpeg, or webp. They are not interchangeable, and picking wrong means either bloated files or lost quality.

WebP is the best default. For a typical webpage render it produces the smallest file at the same visual quality, which adds up fast when you store and serve thousands of images. Use it unless you have a specific reason not to.
PNG is lossless and supports transparency. Reach for it when exact pixel fidelity matters, for example a baseline image in a visual regression test.
JPEG is the safest bet for compatibility with older tooling that predates WebP. It is lossy, so text edges soften slightly.

Switching format is a one-word change in the request body, so you can experiment without rewriting anything.

Capturing the full page, not just the viewport

By default a capture stops at the viewport height you request. To convert the entire scrollable page into one tall image, set full_page to true:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "full_page": true,
    "format": "webp"
  }'

With full_page on, height is ignored and the render extends to the bottom of the document. This is the option you want for archiving a whole article, a long landing page, or anything below the fold. The full-page screenshot guide covers the edge cases (lazy loading, sticky headers) in more depth.

width must be between 320 and 1920 pixels; height between 240 and 1080. If the page renders content client-side after load, add "delay_ms": 1500 to wait before the capture fires, or "selector": "#main" to wait for a specific element to appear.

When a local converter or library is the better call

An API is not always the answer. Skip it and render locally when:

You already have a full HTML string, not a URL. If the markup lives in your app and never gets served at an address, a client-side library such as html2canvas, or a local page.screenshot() in Puppeteer, avoids a round trip. Note that html2canvas reads the existing DOM and does not execute scripts, so it misses dynamically loaded content. See HTML to image for that pattern, including the trick of hosting your template at a URL and then capturing it.
You are doing a single manual capture. Use the browser shortcut from earlier.
You cannot make outbound requests. In an air-gapped environment an API is off the table, so a bundled headless browser is the only option.

For everything else, especially anything that runs on a schedule or in CI, the API path keeps your deployment small and removes an entire class of "it works locally but not in the container" failures.

Next steps

The automated screenshots guide covers scheduling, async jobs, and webhooks for turning many URLs into images in a pipeline. For capturing pages that extend past the viewport, see the full-page screenshot guide, and for rendering your own markup, HTML to image.

Originally published on the Grabbit blog.

@vercel/og vs a Screenshot API: When to Render OG Images with a Real Browser

Nico Acosta — Sun, 19 Jul 2026 11:38:02 +0000

If you build with Next.js, @vercel/og is probably your default for dynamic Open Graph images, and for good reason: it is fast, it runs at the edge, and it is built in. But it renders with satori, which supports only a subset of CSS, and developers keep hitting the same wall. As one put it in a recent r/nextjs thread: "stuck with satori as long as possible tbh, the perf difference is real (its basically instant vs 1-2s for headless). only moved to a screenshot-based approach for like 3 templates out of 40+ that needed actual CSS grid or custom fonts satori chokes on."

That is the whole decision in one sentence. This guide gives you the rule for when to keep @vercel/og and when to render with a real browser instead.

The short answer

Keep @vercel/og for cards you design as a JSX layout (title, author, brand, a gradient) that do not need to match a real page. It is instant and edge-cached.

Reach for a screenshot API when one of two things is true:

satori breaks on your content (CSS grid, right-to-left languages, fonts it cannot load), or
you want the OG image to be a real render of an actual page or app, not a separate layout.

Then cache the rendered image per URL so the slower render happens once, not on every share.

What @vercel/og actually is (and its limits)

@vercel/og converts HTML and CSS into a PNG using satori, a renderer that turns markup into an image without a browser. That is why it is so fast. The tradeoff is that satori supports a deliberately limited slice of CSS:

No CSS grid. Layouts have to be built with flexbox. Anything depending on grid will not render the way you expect.
No bidirectional text. Right-to-left languages like Arabic (ar-SA) and Hebrew (he-IL) can come out broken. A developer in the same thread noted they were evaluating alternatives "primarily because Satori does not support Right To Left layouts and languages... We have customers in the middle east and it straight up breaks."
Every font must be supplied explicitly. You pass each font and weight as data. Miss one and text falls back or fails.

None of this is a bug. satori trades CSS coverage for speed, and for the common case (a templated card you control) it is the right call. The problem is only when your content lives outside that subset.

When a real browser render is the better fit

A screenshot API renders with full Chromium, so it has none of satori's CSS limits. It is the better fit when:

You hit a satori limit. CSS grid, RTL text, a font satori will not load, a CSS feature it does not support. A real browser already handles all of it.
The OG image should be the real page. A dashboard, a chart, a map, a live preview of the actual content. With @vercel/og you would rebuild that as a JSX layout and keep it in sync by hand. A screenshot captures what is already there.
You want one image pipeline across stacks. If not everything you ship is Next.js, a URL-in, image-out API gives every service the same OG path instead of porting satori everywhere.

The honest tradeoff is speed. A real browser render of a page typically takes one to two seconds, where satori is close to instant. You do not want that on the request path for every share, which is what caching is for.

Render once, cache forever

The pattern that makes the screenshot approach practical: render each unique URL once, store the result, and serve the stored image afterward. The slow one-to-two-second render happens a single time per page, and every share after that is a fast static file from your CDN. OG images are a perfect fit for this because the card for a given URL rarely changes.

So the decision is not "fast vs slow on every request." It is "fast layout you maintain in JSX" vs "real render you cache once." Pick based on whether your content fits satori, not on raw latency.

How to render an OG image with a screenshot API

Build or reuse a page at a public URL that shows the title and branding (the same idea as a templated OG route, except it is a real page a browser loads), then capture it at the standard OG size. Here is a single call against Grabbit's API capturing a card at 1200 by 630:

curl -X POST https://grabbit.live/api/v1/grabs \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/og/my-post",
    "width": 1200,
    "height": 630,
    "format": "png",
    "delay_ms": 300
  }'

The response includes the hosted image URL. Store that, point og:image at it, and you are done. The delay_ms gives webfonts and any client rendering a moment to settle before the capture, so the card is never half-painted. Use format: "webp" if you want a smaller file, or jpeg for photographic cards.

If you want the OG image to be the full page rather than a fixed card, add "full_page": true and drop the height, though for social previews the 1200 by 630 card is almost always what you want because that is the exact size platforms render.

A simple decision table

Your situation	Use
Templated card (title, author, brand) in JSX	`@vercel/og`
All-Next.js, content fits satori's CSS subset	`@vercel/og`
RTL language, CSS grid, or a font satori cannot load	Screenshot API
OG image should be a real render of the page or app	Screenshot API
One OG pipeline across multiple stacks, not just Next.js	Screenshot API

It is not either/or for a whole project. The developer who started this was right to keep satori for 40-plus templates and only switch the 3 that broke. Use @vercel/og by default, and reach for a real browser render exactly where satori stops working.

Where to go next

Grabbit is a screenshot API that turns a URL into a hosted image with one call, which is the "real browser render" half of this decision. Pricing is a flat $0.002 per live capture on prepaid credits that never expire, and test keys render free placeholders so you can wire it up before adding a card.

For the surrounding workflow, see how to add dynamic OG images in Next.js (both the native and screenshot paths), how to generate dynamic OG images from any URL, and what an OG image is if you are still getting broken link previews.

Originally published on the Grabbit blog.

How to Take a Website Screenshot in PHP (Browsershot and the API Alternative)

Nico Acosta — Fri, 17 Jul 2026 11:36:01 +0000

PHP has no built-in way to render a web page, so the moment you search for "php screenshot website" you hit a fork: install a headless browser stack and drive it from PHP, or skip the browser and call a hosted API over HTTP. This guide covers both honestly, with working code and the gotcha each one hits. First, a trap to clear out of the way.

The trap: imagegrabscreen is not what you want

The top result people find is PHP's imagegrabscreen(). It captures the operating system's desktop screen, the actual pixels on a monitor. It needs a graphical session, only works where a display is attached, and has nothing to do with loading a URL. On a typical headless Linux web server there is no screen to grab. If you want a screenshot of a website from its URL, imagegrabscreen is the wrong function. You need something that renders the page in a browser.

Approach 1: Spatie Browsershot (the standard DIY route)

Browsershot is the most popular PHP screenshot library. It does not render anything itself; it shells out to a Node.js script that drives Puppeteer and a headless Chromium. So the API is clean PHP, but the work happens in a real browser:

use Spatie\Browsershot\Browsershot;

Browsershot::url('https://example.com')
    ->windowSize(1280, 720)
    ->fullPage()
    ->waitUntilNetworkIdle()
    ->save('example.png');

Install it with composer require spatie/browsershot. The catch is everything that has to exist before that line runs: the server needs Node.js, the puppeteer npm package, and a Chromium binary, all installed and kept current. ->fullPage() captures the entire scrolling page instead of the viewport, and ->waitUntilNetworkIdle() is how you avoid capturing a half-loaded page. Browsershot is the right pick when you control the server and can run that Node plus Chromium stack. It is the wrong pick when you are on shared hosting, a locked-down container, or a platform where you would rather not babysit a browser.

The gotcha: waiting for the page

The most common bug in any headless capture is firing the screenshot before the page is ready. Do not lean on a fixed sleep. Browsershot gives you real signals:

Browsershot::url('https://example.com')
    ->waitUntilNetworkIdle()
    ->waitForFunction('document.fonts.ready')
    ->setDelay(500)
    ->save('example.png');

waitUntilNetworkIdle() waits for in-flight requests to settle, waitForFunction('document.fonts.ready') avoids a fallback-font flash, and setDelay adds a final cushion in milliseconds for animations or late hydration. The same class of problem and the same controls show up whether you drive Puppeteer directly in Node or a browser in Python.

Approach 2: Skip the browser, call an API

Browsershot means you install and operate a browser on your PHP server: Node, Puppeteer, a Chromium binary, the memory each headless instance eats, and the upgrade treadmill when Chrome ships a breaking change. If screenshots are a production feature rather than a one-off script, a screenshot API removes all of that. You send one HTTP request:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "full_page": true,
    "format": "webp"
  }'

The same call from PHP with Guzzle:

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://api.grabbit.live/v1/grabs', [
    'headers' => ['Authorization' => 'Bearer sk_live_...'],
    'json' => [
        'url' => 'https://example.com',
        'width' => 1280,
        'full_page' => true,
        'format' => 'webp',
    ],
]);

$imageUrl = json_decode((string) $response->getBody(), true)['image_url'];

The response is a hosted image URL you can store and reuse:

{
  "id": "grb_01jx...",
  "status": "done",
  "image_url": "https://cdn.grabbit.live/grabs/grb_01jx....webp",
  "width": 1280,
  "format": "webp",
  "bytes": 48210,
  "execution_ms": 1180
}

The Browsershot options map cleanly onto request parameters: window size is width (320 to 1920) and height (240 to 1080), ->fullPage() is full_page, the wait becomes delay_ms (0 to 10000), and a single-element capture is a selector field. format is png, jpeg, or webp. There is no Node, Puppeteer, or Chrome to install on your side, because the render runs on the provider's infrastructure.

Which to use

You control the server and can run Node plus Chromium: Browsershot. It is well maintained and gives you full control over the headless browser.
Shared hosting, a slim container, or you would rather not operate a browser: a screenshot API, so PHP just makes an HTTP request.
Whatever you do, not imagegrabscreen: it captures the desktop, not a web page.

For the same decision in other languages, see screenshots in Python and screenshots in Node.js. If you are weighing hosted providers, the honest comparison of screenshot APIs covers the trade-offs without the marketing. Test-environment keys render free placeholders, so you can wire the request into your PHP code before adding a card.

Originally published on the Grabbit blog.

How to Automate Website Screenshots in GitHub Actions

Nico Acosta — Thu, 16 Jul 2026 11:37:23 +0000

To screenshot a website in GitHub Actions, add a workflow step that sends the URL to a screenshot API and saves the image it returns. The API renders the page in a hosted browser, so the step is a single curl command with no browser to install in the runner and no headless-Chrome flags to debug. That is the short answer. The rest of this guide covers the full workflow, the difference between capturing a URL and capturing your test run, scheduled snapshots, and the headless-Chrome path if you would rather run the browser yourself.

Two different jobs people call "screenshot in CI"

The search results for this mix two tasks that need different tools. Sort out which one you have first:

Capture an external URL. You want an image of a live page (your production site, a staging deploy, a competitor) as part of a workflow. This is a render-the-URL problem, and the cleanest path is one API request. Most of this guide is about this.
Capture the app under test. Your job already runs Playwright, Cypress, or a Compose UI test, and you want the screenshot that test produced (often on failure) attached to the run. That image comes from the test framework itself, then actions/upload-artifact carries it out. We cover that path near the end.

If you are setting up visual regression, you likely want both: the test framework captures the app it is driving, and a hosted render gives you consistent baselines for pages and external URLs the test does not control. Visual regression testing goes deeper on that split.

Why headless Chrome is painful inside a runner

The reason "screenshot github actions not working" is a real related search: CI runners are a hostile place to run a browser. The recurring failure modes are:

Timing. The capture fires before the page finishes loading, so you get a blank or half-rendered image. You have to wait for network idle, not just DOMContentLoaded.
Fonts. The Ubuntu runner ships a minimal font set. Pages that use system or web fonts render with tofu boxes or fall back to a different face, so the screenshot does not match what users see.
Viewport. The default window size is not the viewport you want, so the layout that renders is not the layout you meant to capture.
Maintenance. Every Chromium bump can change a flag, and you own the dependency list, the version pinning, and the install time on every run.

None of this is hard once, but it is a standing tax on the workflow. Offloading the render removes it.

The one-step workflow: screenshot a URL

Here is a complete workflow that captures a URL on every push and saves the image as an artifact. The capture itself is one step.

# .github/workflows/screenshot.yml
name: Screenshot site
on: [push]

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - name: Capture screenshot
        run: |
          IMAGE_URL=$(curl -s https://api.grabbit.live/v1/grabs \
            -H "Authorization: Bearer ${{ secrets.GRABBIT_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "url": "https://example.com",
              "width": 1280,
              "height": 720,
              "format": "webp"
            }' | jq -r '.image_url')
          curl -s "$IMAGE_URL" -o screenshot.webp

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: site-screenshot
          path: screenshot.webp

What each piece does:

The capture step POSTs the URL to the API. width pins the desktop layout, height gives a 16:9 above-the-fold crop, and format of webp keeps the artifact small. The response is JSON; jq pulls out the image_url.
The second curl downloads the hosted image into the workspace as screenshot.webp.
actions/upload-artifact attaches that file to the run, so you can open it from the run summary.

Store your key as a repository secret (GRABBIT_API_KEY) and reference it with ${{ secrets.GRABBIT_API_KEY }} so it never lands in the workflow file. The runner needs no browser, no font install, and no apt-get step. ubuntu-latest already has curl and jq.

For pages whose content loads after the first paint, add "delay_ms": 800 so lazy images settle before the capture. To capture the whole document instead of the top crop, set "full_page": true and drop height. To capture one component, such as a hero or a pricing card, pass "selector": "#hero".

Screenshot on a schedule

A common reason to put captures in CI is to build a running history: a daily snapshot of your landing page or a dashboard. Swap the push trigger for a schedule and the same workflow runs on a cron cadence with no commit needed.

on:
  schedule:
    - cron: "0 9 * * *" # every day at 09:00 UTC
  workflow_dispatch: # also allow a manual run

Each run captures the URLs you list and uploads the images. Add a commit step if you want the snapshots versioned in the repo, or keep them as artifacts if you only need recent history. To capture several pages, loop over a list of URLs and call the API once per URL; how to screenshot a list of URLs covers that loop.

Screenshot the app your test is driving

If your job already runs a browser test, the screenshot comes from the test, not from a separate render. Capture it in the framework and upload the file:

Playwright: call await page.screenshot({ path: 'shot.png' }), or let the runner capture on failure with screenshot: 'only-on-failure' in your config. The artifacts land in test-results/.
Cypress: cy.screenshot() writes to cypress/screenshots/, and the runner captures automatically on a failed test.

Then attach them:

      - name: Upload test screenshots
        if: always() # upload even when the test failed
        uses: actions/upload-artifact@v4
        with:
          name: test-screenshots
          path: test-results/

The if: always() matters: without it, a failed test step skips the upload, and the failure screenshot you most want is the one you lose. For the full setup of capturing inside a Playwright run and comparing against a baseline, see visual testing in Playwright CI.

When to use the API vs the framework

A quick rule:

Use the API when you are capturing a URL the workflow does not run: production, a deployed preview, an external site, or a page you want a consistent baseline of regardless of the CI environment. One request, no browser to maintain, and the same render every time because the font set and viewport are fixed on the API's side.
Use the framework when you are capturing the app the job is already driving through a test, especially failure screenshots tied to a specific assertion.

Many pipelines use both, and that is fine. The point of moving the URL captures to an API is that the part of CI most likely to break (a headless browser on a minimal runner) becomes an HTTP call that does not.

Putting it together

To automate website screenshots in GitHub Actions: POST the URL to a screenshot API in a single workflow step, download the returned image, and upload it as an artifact. Add a schedule trigger for daily snapshots, and reach for your test framework's own screenshot for the app under test. The runner stays clean, the captures stay consistent, and there is no browser to install or keep working.

For the full set of capture options (viewport, format, full-page, selector, delay) see the screenshot API. For running captures across many URLs on a schedule, see automated screenshots. And if you are wiring screenshots into a test suite rather than a plain workflow, visual regression testing covers the baseline-and-compare loop end to end.

Originally published on the Grabbit blog.

How to Screenshot a Specific Element on a Page (With a CSS Selector)

Nico Acosta — Wed, 15 Jul 2026 11:39:39 +0000

To screenshot a specific element instead of the whole page, target it with a CSS selector and capture only its bounding box. You can do this three ways: manually in the browser's DevTools, in code with a headless browser, or over an API by sending the page URL and the selector. Which one fits depends on whether it is a one-off, whether you control the page, and how many elements you need to capture.

This guide covers all three, the difference between a true element screenshot and a client-side <div> re-render, and why element capture is often the right call for monitoring a single component.

The manual way: DevTools node screenshot

For a quick one-off, the browser already does this. In Chrome:

Right-click the element and choose Inspect to select its node in the Elements panel.
Open the Command Menu with Cmd/Ctrl + Shift + P.
Type screenshot and choose Capture node screenshot.

Chrome saves a PNG cropped to that element. Firefox has the same feature: in the Inspector, right-click a node and pick Screenshot Node. This is perfect when you need one image once. It does not help when you need the same element from many pages, on a schedule, or from a server, which is where the next two paths come in.

The code way: capture an element's bounding box

Every headless browser can screenshot a single element. The shape in Puppeteer:

// DIY: find the element, screenshot only its box
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto(url, { waitUntil: 'networkidle2' });
const el = await page.$('#pricing-table');
await el.evaluate((node) => node.scrollIntoView());
await el.screenshot({ path: 'element.png' });
await browser.close();

Playwright is page.locator('#pricing-table').screenshot(). Selenium 4 added it too: find the element, then call getScreenshotAs (Java) or .screenshot() (Python) on the element itself. See how to take screenshots in Selenium for the full element-capture example there.

Two things bite people:

Scroll into view. If the element is below the fold, the capture can come back clipped or blank. Scroll it into view first.
Wait for it to render. If the element is populated by JavaScript after load, the selector resolves before the content paints. Wait for the element, or add a short delay, before capturing.

This is the right path when the page is yours and you are already running a browser. The cost is the same as any DIY screenshot setup: you own the browser pool, the scaling, and the storage.

The API way: send a URL and a selector

When you want one element from a page you do not control, or the same element across many URLs, sending the work to a screenshot API is the shortest path. You pass the page URL and a CSS selector, and you get back an image cropped to that element. No browser to run, no scroll-and-wait logic to maintain:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://stripe.com/pricing",
    "selector": ".PricingTable",
    "format": "webp",
    "delay_ms": 800
  }'

The API renders the real page in a browser, finds the element matching selector, and returns an image_url pointing at a hosted capture of just that element. delay_ms of 800 gives content that loads after first paint time to settle before the capture. format of webp keeps the file small.

A few notes on the parameters:

selector takes any CSS selector: an id (#hero), a class (.PricingTable), or a more specific path. If it matches multiple elements, the first match is captured.
width still sets the viewport the page renders at (320 to 1920), which decides whether the element renders in its desktop or mobile layout before it is cropped. Leave it at the default 1280 for a desktop render.
Skip full_page here. Element capture and full-page capture are different jobs: selector crops to one element, full_page captures the entire document. If you want the whole page instead, see how to take a full-page screenshot.

Element screenshot vs a client-side div re-render

There is a popular fourth approach that looks like an element screenshot but is not one: html2canvas and similar libraries. These run in the user's browser and redraw a DOM node onto a <canvas>. That is a re-render of the DOM, not a capture of what the browser actually painted, so it has real limits:

It can miss or blank out cross-origin images the canvas cannot read.
Complex CSS (filters, some gradients, transforms, custom fonts) often renders differently from the real page.
It only works on a page already loaded in a browser you control, so it is no help for capturing an element from an external URL.

For a faithful image of an element as a browser renders it, you want a real render: headless Chrome in code, or a screenshot API. The client-side canvas trick is fine for capturing something inside your own running app (a generated chart, a receipt) where pixel-perfect fidelity to the live page does not matter.

When to capture one element instead of the whole page

Element capture is not just a smaller screenshot. For some jobs it is the better one:

Component monitoring. Watching a single pricing table, status banner, or hero for changes is cleaner against just that element. A full-page diff lights up every time an unrelated ad or footer shifts; an element capture only changes when the thing you care about does. This pairs naturally with visual regression testing.
Embedding a specific piece. Pulling one card, chart, or quote out of a page to show elsewhere is exactly an element crop.
Stable captures across pages. Capturing .product-card across a catalog gives you uniform images without per-page cropping math.

Putting it together

To screenshot a specific element: pick it with a CSS selector, then capture only its bounding box. For a one-off, DevTools' node screenshot is instant. In your own app with a browser already running, screenshot the element in Puppeteer, Playwright, or Selenium. For an element from a URL you do not control, or the same element across many pages, send the URL and selector to an API and get back a cropped image with no browser to run.

For every capture option (viewport, format, full-page, selector, delay) see the screenshot API. To capture whole pages from URLs, see how to screenshot a website from a URL.

Originally published on the Grabbit blog.

How to Generate a Website Preview Image from a URL

Nico Acosta — Tue, 14 Jul 2026 11:40:46 +0000

A website preview image is a rendered picture of a web page, almost always a screenshot of the page captured in a real browser. Link directories, dashboards, "recently added site" feeds, portfolio grids, and monitoring tools all show one so a person can recognize a site at a glance without loading it. To generate a preview from a URL, send the URL to a screenshot API and store the image it returns.

The preview itself is the easy part. The work is rendering the page faithfully, at the right size, for many URLs, on a schedule, without running a browser fleet yourself. This guide covers what a website preview actually is, how it differs from a social link preview, what size to capture, the build-it-yourself path, and the one-call API path.

Website preview vs social link preview

Search results for "website preview" mix two different jobs, so it is worth separating them up front:

A website preview image is a screenshot of the page. You generate it for sites you link to, list, or watch, and it refreshes when you recapture. This is a render-the-URL problem.
A social link preview is the og:image a site sets for itself, the card that shows when its link is shared on Slack, Discord, X, or LinkedIn. It is a hand-designed image, not a live screenshot, and you control it only for your own pages.

This post is about the first one: turning a URL into a real rendered image you can show. If you are trying to fix the card that appears when your own link is shared, that is an Open Graph problem. See what is an OG image for that path instead.

There is also a third thing people call a "preview": the browser-extension popup that shows a live page when you hover a link. That is an in-browser convenience, not an image you can store, host, or put in a dashboard. For anything programmatic you want a captured image, which is what the rest of this guide produces.

What size should a website preview be

Capture at a desktop viewport width, then display the result scaled down. The two decisions are separate:

Capture width sets which layout renders. 1280px is a safe default: it triggers the desktop layout most visitors see. Rendering at a tiny viewport instead pushes the page into its mobile breakpoint, so the preview shows a hamburger menu and a single stacked column, which is not a recognizable preview of the site.
Displayed size is a CSS concern. Render the captured image into whatever box your grid or card uses. Downscaling a wide capture keeps text crisp and the layout faithful.

For the most common framing, an above-the-fold preview, capture a fixed height rather than the whole page. A 1280x720 capture gives you a clean 16:9 crop of the top of the page. When you want the entire document (long landing pages, articles), use full_page instead and let the height grow.

The build-it-yourself path

You can generate previews with headless Chrome. The shape in Puppeteer:

// DIY: you own the browser, the scaling, and the storage
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 720 });
await page.goto(url, { waitUntil: 'networkidle2' });
const buffer = await page.screenshot({ type: 'png' });
await browser.close();
// then: upload to storage, store the URL, serve the image

That works for one URL on your laptop. The cost shows up at scale:

Infrastructure. Each capture needs a Chromium process. Previewing a directory of hundreds of sites means a browser pool, a queue, and memory limits, because one runaway page can take down the box.
Reliability. Cookie and consent banners, lazy-loaded images, and pages that block headless browsers all produce blank or broken previews unless you handle each case.
Storage. You still have to upload, host, and serve every image yourself.

For a handful of static previews this is fine. For an automated, always-current feed it becomes a service you maintain.

The one-call API path

A screenshot API does the rendering and hosting, so your code is just the request. Send the URL, get back a hosted image:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://stripe.com",
    "width": 1280,
    "height": 720,
    "format": "webp"
  }'

width pins the desktop layout. height of 720 gives a 16:9 above-the-fold crop, the classic preview frame. format of webp keeps the file small, which matters when a feed loads many previews at once. The response includes an image_url pointing at the stored capture. Save that URL and render it in your <img> or as a CSS background-image in the card.

Want the entire page instead of the top crop? Set "full_page": true and drop height. For pages whose content loads after the first paint, add "delay_ms": 800 so lazy images settle before the capture. To preview just one part of the page, such as a hero or a pricing card, pass "selector": "#hero" and only that element is captured.

Generating previews in bulk

A directory or feed is the same request in a loop. There is no separate batch endpoint to learn:

Iterate over your list of URLs.
Call the API once per URL with the same width, height, and format.
Store each returned image_url keyed by the source URL.
Render the stored URLs in your grid or feed.

Because the API owns the browser pool, capturing a hundred previews is the same code as capturing one. If you are building this around a list of sites, how to screenshot a list of URLs covers the loop, concurrency, and error handling in depth.

Keeping previews current

A preview goes stale the moment the source site redesigns. The fix is to recapture, but recapturing on every page load is wasteful. The pattern:

Cache the image_url. Store it with the source URL and a captured-at timestamp. Serve the cached image, not a fresh capture, on every request.
Refresh on a schedule. Recapture each URL on a cadence that matches how often the sites change. A daily refresh is plenty for most feeds; weekly is fine for stable portfolios.
Refresh on demand. Let users trigger a recapture for their own listing so a redesign shows up immediately instead of waiting for the next run.

This keeps the feed current without rendering a browser on every request.

Putting it together

To generate a website preview image from a URL: capture at a desktop width, request a small format, store the returned image URL, and recapture on a schedule. With a hosted API the whole thing is one request per URL plus a cache, with no browser fleet to run.

For the full set of capture options (viewport, format, full-page, selector, delay) see the screenshot API. For running previews across many URLs on a schedule, see automated screenshots. And if you want the top crop versus the whole document, how to generate a website thumbnail from a URL walks through the framing choices in detail.

Originally published on the Grabbit blog.

Twitter Card Image Size: The Right Dimensions for X Link Previews

Nico Acosta — Mon, 13 Jul 2026 11:40:44 +0000

When you paste a link into a tweet, X should unfurl it into a card with a title, a description, and an image. The single setting that decides whether that image shows up large or as a cramped thumbnail is the Twitter card image size. Get the dimensions right and one image gives you a full-width preview on X and every other platform. Get them wrong and the card collapses to a small square or shows no image at all.

The short answer

For a large, full-width card on X, use 1200 by 628 pixels at a 1.91 to 1 aspect ratio. That is the size for a Summary Card with Large Image, the card type you almost always want.

A few details that matter:

Aspect ratio is what X actually enforces. The card is 1.91 to 1. 1200 by 628 hits it; the near-identical 1200 by 630 Open Graph size renders the same way, so you do not need a separate image for X.
Maximum 4096 by 4096 pixels, under 5MB. Above that, X will not render the image. Stay well under.
Formats: JPG, PNG, or WebP. (Animated GIFs are not supported on cards.)
The small Summary Card is different. If you use summary instead of summary_large_image, the image is a square thumbnail beside the text, minimum 144 by 144 pixels. This guide focuses on the large card.

Because 1200 by 628 is effectively the same 1.91 to 1 frame Facebook, LinkedIn, Discord, and Slack use, a single correctly sized image covers all of them.

How X builds a link card

X does not screenshot your page or guess at its content. When a URL is posted, X fetches the raw HTML and reads two families of meta tags from the <head>: the twitter: tags and, as a fallback, the Open Graph og: tags.

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Your Page Title" />
<meta name="twitter:description" content="A one-line summary of the page." />
<meta name="twitter:image" content="https://yourdomain.com/og.png" />

<!-- Open Graph fallbacks X also reads -->
<meta property="og:title" content="Your Page Title" />
<meta property="og:description" content="A one-line summary of the page." />
<meta property="og:image" content="https://yourdomain.com/og.png" />

The one tag with no Open Graph equivalent is twitter:card. It tells X which layout to use; summary_large_image is what gives you the 1.91 to 1 banner. For everything else, X falls back to the og: tag when the matching twitter: tag is missing. So in practice you can set twitter:card plus the four og: tags and skip the redundant twitter:title, twitter:description, and twitter:image. That is why the same image and tags that fix a LinkedIn link preview or a Discord link preview also fix the X card.

Two things trip people up:

X reads the raw HTML, not the rendered page. It does not run your JavaScript. If your meta tags are set client-side (a single-page app that injects them after load), X never sees them. The tags must be in the HTML the server sends.
twitter:image / og:image must be an absolute, public URL. A relative path like /og.png will not resolve, and an image behind a login or a redirect X cannot follow renders as no image. Use the full https://yourdomain.com/og.png and confirm it loads in a private browser window.

Making the card image a real render of your page

The hardest part of a good card is not the four meta tags. It is producing an image at exactly 1200 by 628 that actually reflects the page, instead of a generic logo. For a marketing page, a docs page, or a launch announcement, the most compelling preview is often a clean shot of the page itself.

You can produce that with a screenshot API: point it at the URL, get back a hosted image at the size you ask for, and use that image as your og:image / twitter:image.

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourdomain.com/og",
    "width": 1200,
    "height": 628,
    "format": "png",
    "delay_ms": 500
  }'

The response includes a hosted image_url:

{
  "id": "grb_01jx...",
  "status": "done",
  "image_url": "https://cdn.grabbit.live/grabs/grb_01jx....png",
  "width": 1200,
  "height": 628,
  "format": "png",
  "bytes": 68820,
  "execution_ms": 1180
}

width accepts 320 to 1920 and height 240 to 1080, so the 1200 by 628 card is in range. delay_ms (0 to 10000) gives client-rendered content or web fonts a moment to settle before the capture fires. Drop the returned image_url into your tags:

<meta name="twitter:image" content="https://cdn.grabbit.live/grabs/grb_01jx....png" />
<meta property="og:image" content="https://cdn.grabbit.live/grabs/grb_01jx....png" />

Capture once per unique page and cache the image_url alongside the page record rather than rendering on every request. A common pattern is to build a dedicated /og route with your normal components, capture that at 1200 by 628, and reuse the result everywhere. The same template-and-cache approach is covered in how to generate dynamic OG images from any URL.

How to validate the card

X retired its standalone Card Validator, so the old "paste a URL into the validator" workflow no longer exists. There are three reliable ways to check a card before it goes out (covered in depth in how to test your X link preview now that the validator is gone):

Draft the tweet. Paste the URL into the X composer (or a test account) and look at the preview it renders. This is the ground truth, since it is X reading your live tags.
Inspect the tags directly. Run view-source on the live URL or curl it and confirm the twitter:card and og:image tags are present in the served HTML, before any JavaScript runs.
Use a third-party Open Graph debugger. Because X reads the same og: tags, a general Open Graph preview tool shows you how the card will look. Our OG image checker walks through previewing the image before you publish.

If the card looks wrong even though the tags are correct, the cause is almost always caching: X stored the metadata from the first time the URL was shared. Append a unique query string such as ?v=2 to the URL when you re-post, and X treats it as a new link with no cache entry.

Why your card still is not showing

If the tags are present, the image URL works in a browser, and you have re-posted with a cache-busting query string but the card still looks wrong, work through these:

The image is behind auth or a redirect. If twitter:image requires a login, sits behind a paywall, or redirects in a way X will not follow, the card renders without an image. Test the raw image URL in a private window.
Tags are set by JavaScript. X reads static HTML and does not execute scripts. Server-render the meta tags.
The image is the wrong shape or too small. Below the 1.91 to 1 ratio, X may show a small square thumbnail instead of a full-width banner, or fall back to the small card. Use 1200 by 628.
twitter:card is missing. Without summary_large_image, X defaults to the small summary card, so even a correctly sized image appears as a thumbnail. Set the card type explicitly.

Work top to bottom: confirm twitter:card is summary_large_image first, then verify the image is public and absolute, then bust the cache by re-posting with a fresh query string.

The short version

A Twitter (X) card is just your page's twitter: and Open Graph tags, rendered as a preview. Set twitter:card to summary_large_image, point og:image / twitter:image at an absolute, public 1200 by 628 image, and X gives you a full-width card that also covers Facebook, LinkedIn, Discord, and Slack. The validator is gone, so check the card by drafting a tweet or inspecting the served tags. If you want the image to be a real render of the page instead of a static logo, a screenshot API turns the live URL into the hosted image you point the tags at. If you are new to the format, start with what is an OG image.

Originally published on the Grabbit blog.