shot-scraper: Automated Documentation Screenshots (and When an API Fits Better)

shot-scraper is a command-line tool by Simon Willison, built on Playwright for Python, for taking automated screenshots of web pages. Its original and best-known job is keeping the screenshots in your documentation up to date, so a feature screenshot does not quietly drift out of date every time the UI changes. You declare the shots you want in a YAML file, run one command, and every image regenerates.

This guide covers what shot-scraper does, how its documentation-as-code workflow is set up, how to run it in CI, and the honest trade-off: when the tool is exactly right, and when a hosted screenshot API is the simpler fit.

What shot-scraper actually does

The core command takes one screenshot:

shot-scraper https://example.com -o example.png

That launches a headless Chromium through Playwright, loads the page, and writes a PNG. On its own that is not very different from a dozen other tools. What makes shot-scraper worth knowing is the multi command, which reads a YAML manifest and regenerates a whole set of shots at once:

# shots.yml
- output: docs/images/homepage.png
  url: https://example.com/
- output: docs/images/pricing.png
  url: https://example.com/pricing
  height: 800
- output: docs/images/settings.png
  url: https://example.com/settings
  selector: "#settings-panel"

shot-scraper multi shots.yml

Now the manifest, not a person with a screen-capture key, is the source of truth for what the docs show. When the pricing page changes, you rerun the command and the image updates. That is the docs-as-code idea applied to screenshots, and it is the reason the tool exists. Willison described it on release as "a tool for keeping screenshots in documentation up-to-date," and that framing is still the strongest reason to use it.

shot-scraper also does two things a pure screenshot tool does not: it can execute JavaScript against a loaded page and return the result (scraping), and it can record WebM videos from a storyboard. If those are jobs you have, the tool earns its place on that alone.

Automating it in CI

The documentation-as-code pattern only pays off when the regeneration is automatic. shot-scraper ships a template repository that wires it into GitHub Actions: on a schedule, the workflow installs the tool, runs the manifest, and commits any changed images back to the repo. A trimmed version of the workflow looks like this:

# .github/workflows/shots.yml
on:
  schedule:
    - cron: "0 6 * * *"
  workflow_dispatch:

jobs:
  shots:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install shot-scraper
      - run: shot-scraper install        # downloads the Playwright browser
      - run: shot-scraper multi shots.yml
      - run: |                            # commit any changed screenshots
          git add -A
          git diff --quiet && git diff --staged --quiet || \
            git commit -m "Update screenshots" && git push

This is a genuinely good setup, and for a project that already lives in GitHub it is close to free to adopt. The line to pay attention to is shot-scraper install. That is Playwright downloading a browser and its system libraries into the runner on every run. It works, but it is the part you now own: the browser version, its dependencies, and the minutes each run spends installing it.

The honest trade-off

shot-scraper is excellent at what it was built for. The question is whether you want to run a browser at all.

Everything shot-scraper does, it does by installing Chromium through Playwright and driving it locally (or in your CI runner). That is the right model when you need the full toolkit: JavaScript scraping, PDF export, video recording, or screenshots of pages behind a login flow you script yourself. It is more than you need when the job is simply "turn these URLs into images and keep them current."

For that narrower job, a hosted screenshot API collapses the whole setup into one HTTP request per shot, with no browser to install or patch. The same three documentation screenshots from the manifest above become three calls:

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 includes an image_url pointing at the stored capture, which you commit into the docs or reference directly. There is no shot-scraper install step, no Playwright browser in the runner, and no system libraries to keep patched. The parameters map onto the same consistency controls shot-scraper exposes: width (320 to 1920) pins the viewport so layout is identical every run, full_page captures the whole document, delay_ms (0 to 10000) waits for lazy-loaded content to settle, format accepts png, jpeg, or webp, and selector scopes the capture to a single element, exactly like the selector field in the YAML manifest.

Here is the decision in one table:

Neither is "better" in the abstract. shot-scraper trades a browser install for a self-contained, scriptable tool. An API trades the tool's full feature set for having no browser to own. Pick the one whose cost you would rather carry.

Cost, honestly

shot-scraper is free and open source, so its only cost is the CI minutes and the maintenance of the Playwright runtime it installs. A hosted API has a per-capture price but no runtime to maintain. Grabbit is $0.002 per live grab, so a docs set of 30 screenshots regenerated daily is 900 grabs a month, roughly $1.80. Annual-plan credits do not reset monthly, which suits documentation builds that run unevenly, and synchronous test requests return placeholder images at no charge so you can wire up the workflow before any real capture runs. Other tools, shot-scraper included, carry no per-grab fee at all. So if avoiding any usage cost is the priority, running the browser yourself is the honest answer. The API's trade is the reverse: a small per-capture price in exchange for never maintaining the browser.

Where to go next

If you are building scheduled or release-triggered capture into a docs pipeline, automated screenshots covers the API side in depth, and screenshot automation walks through wiring a scheduler to the render step. If your captures live in CI specifically, how to automate website screenshots in GitHub Actions shows the single-step workflow. And if you are starting from one URL, how to screenshot a website from a URL is the shorter entry point.