Screenshot URL

The quickest way to use the ScreenshotRun API is with a simple URL. The GET /v1/screenshots/capture endpoint returns an image directly — you can use it in <img> tags, links, emails, or anywhere a URL works. No JavaScript, no server-side code, no polling.

How It Works

Build a URL by adding your parameters as query string values. When you (or a browser) requests this URL, the API captures the screenshot and returns the image file directly.

https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=png&width=1280

You still need to authenticate. Pass your API key in the Authorization header, or use a domain-restricted API key for client-side usage.

Building a Screenshot URL

Start with the base URL and add parameters:

https://api.screenshotrun.com/v1/screenshots/capture
  ?url=https://example.com     ← page to capture
  &format=webp                  ← output format
  &width=1280                   ← viewport width
  &height=800                   ← viewport height
  &full_page=true               ← capture full scrollable page

All parameters from Screenshot Options are supported. Just pass them as query string values.

Use in HTML

As a link

<a href="https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=png">
  Download Screenshot
</a>

When the user clicks the link, the browser downloads the screenshot image.

As an image

<img
  src="https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=webp&resize_width=640"
  alt="Website screenshot"
  loading="lazy"
>

With caching

<img
  src="https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=webp&resize_width=640&cache_ttl=86400"
  alt="Website screenshot"
>

With cache_ttl=86400, the screenshot is cached for 24 hours. Subsequent requests return the cached image instantly without using your quota.

Thumbnail Gallery

Build a website thumbnail gallery by looping through URLs:

php Copy

@foreach($websites as $site)
  <div class="thumbnail">
    <a href="{{ $site->url }}">
      <img
        src="{{ config('app.api_url') }}/screenshots/capture?url={{ urlencode($site->url) }}&format=webp&resize_width=320&cache_ttl=86400"
        alt="{{ $site->name }}"
        loading="lazy"
        width="320"
      >
    </a>
    <p>{{ $site->name }}</p>
  </div>
@endforeach

javascript Copy

function WebsiteThumbnail({ url, name }) {
  const apiUrl = `https://api.screenshotrun.com/v1/screenshots/capture`;
  const params = new URLSearchParams({
    url,
    format: "webp",
    resize_width: "320",
    cache_ttl: "86400",
  });

  return (
    <div className="thumbnail">
      <a href={url}>
        <img
          src={`${apiUrl}?${params}`}
          alt={name}
          loading="lazy"
          width={320}
        />
      </a>
      <p>{name}</p>
    </div>
  );
}

Use in Email

You cannot use live API URLs in emails because email clients don't send authorization headers. Instead, capture the screenshot first, then embed the image.

Option 1: Download and attach

import requests

# Capture the screenshot
response = requests.get(
    "https://api.screenshotrun.com/v1/screenshots/capture",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"url": "https://example.com", "format": "png", "resize_width": "600"},
)

# Save locally, then attach to your email
with open("preview.png", "wb") as f:
    f.write(response.content)

Option 2: Use a signed URL

Create a signed URL and embed it in the email. Signed URLs don't require authentication:

<img src="https://api.screenshotrun.com/v1/screenshots/550e8400-.../signed-image?expires=...&signature=..." alt="Preview">

Use in Markdown / README

If you want to embed a live screenshot in a Markdown file or README, capture it once, save to your repository, and reference the file. Using a live API URL in Markdown won't work because there's no way to pass the Authorization header.

# Capture and save to your repo
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=png&resize_width=800" \
  -o docs/images/example-screenshot.png

![Example screenshot](docs/images/example-screenshot.png)

URL Encoding

Remember to URL-encode your parameter values, especially the url parameter. Most HTTP clients handle this automatically, but when building URLs manually:

# Wrong — the & in the target URL will break the query string
?url=https://example.com/page?id=1&lang=en&format=png

# Correct — target URL is encoded
?url=https%3A%2F%2Fexample.com%2Fpage%3Fid%3D1%26lang%3Den&format=png

Security

If you use screenshot URLs in client-side code (HTML, JavaScript), your API key could be exposed in the page source. To protect it:

• Domain-restrict your API key. In the dashboard, set allowed domains for the key. The API will only accept requests with a matching Origin or Referer header.
• Use a server-side proxy. Have your backend make the API call and return the image to the browser. This keeps your API key hidden.
• Use signed URLs. Capture once, generate a signed URL, and embed that instead.