What is BrowserGrab?

BrowserGrab is a screenshot API that captures any public webpage as a pixel-perfect image with a single HTTP request. No browser to run, no Puppeteer to manage — just send a URL and get back an image.

It runs on Cloudflare's global network, so captures are fast from anywhere in the world. You can store results on BrowserGrab's CDN, save directly to Google Drive, or receive the raw image as a base64 string in the API response.

Quick Start

Get your first screenshot in under a minute:

Authentication

All API requests require a Bearer token in the Authorization header. Create and manage your keys from the API Keys page.

Authorization: Bearer bg_live_xxxxxxxxxxxxxxxxxxxx

Keep your keys secret — they carry your quota. If a key is compromised, delete it from the dashboard and create a new one.

Parameters

Send a JSON body to POST /api/screenshot. Only url is required — everything else has a sensible default.

Core (all plans)

Super plan only

Bulk Screenshots

Capture up to 20 URLs in a single API call. Each URL counts as one screenshot credit. The entire batch is checked against your quota upfront — if you don't have enough credits for all URLs, the whole request is rejected rather than processing a partial batch.

Two ways to send multiple URLs

{
  "urls": [
    "https://example.com",
    "https://github.com",
    "https://stripe.com"
  ],
  "format": "png",
  "width": 1280,
  "storage": "cloud"
}

{
  "url": "https://example.com,https://github.com,https://stripe.com",
  "format": "png"
}

Bulk response shape

When 2 or more URLs are sent, the response wraps individual results in a results array. Each item has its own success flag and charged indicator.

{
  "success": true,
  "count": 3,
  "captured": 2,
  "failed": 1,
  "results": [
    {
      "url": "https://example.com",
      "success": true,
      "data": {
        "url": "https://pub-....r2.dev/screenshots/2025-04/abc123.png",
        "width": 1280,
        "height": 800,
        "format": "png",
        "storage": "cloud"
      },
      "charged": true
    },
    {
      "url": "https://github.com",
      "success": true,
      "data": { "url": "https://pub-....r2.dev/screenshots/...", ... },
      "charged": true
    },
    {
      "url": "https://bad-url.xyz",
      "success": false,
      "error": "page_load_failed",
      "message": "DNS lookup failed",
      "charged": false
    }
  ]
}

Bulk behaviour

Storage Options

The storage parameter controls where the screenshot ends up after capture.

CDN URLs are permanent — they don't expire. You can link to them directly in emails, embed them in <img> tags, or store them in your own database.

Response Format

All responses are JSON. A successful capture returns:

{
  "success": true,
  "data": {
    "url": "https://pub-....r2.dev/screenshots/2025-04/abc123.png",
    "width": 1280,
    "height": 800,
    "format": "png",
    "storage": "cloud"
  }
}

data.url is the image you store or display. For storage: "none" this is a base64 data URL instead of a CDN link.

Error Codes

Errors follow a consistent shape: { "error": "code", "message": "Human description" }. The charged field will be false when no screenshot credit was consumed.

Rate Limits

There is no per-second rate limit — burst as fast as you like within your monthly allocation. Quotas reset on the 1st of each month UTC. Need more? Contact us for a custom plan.

JavaScript / TypeScript SDK

The official SDK is published on npm as browsergrab. Zero dependencies. Works in Node.js 18+, Deno, Bun, and any runtime with the Fetch API. Full TypeScript types included.

Installation

npm install browsergrab

Usage

import BrowserGrab from "browsergrab";

const client = new BrowserGrab("bg_live_your_api_key");

// Basic screenshot — returns CDN URL
const result = await client.screenshot({
  url: "https://stripe.com",
});
console.log(result.url); // https://pub-....r2.dev/screenshots/...

// Full page in WebP with dark mode (Super plan)
const dark = await client.screenshot({
  url: "https://github.com",
  format: "webp",
  fullPage: true,
  darkMode: true,
  storage: "cloud",
});

// Mobile viewport
const mobile = await client.screenshot({
  url: "https://example.com",
  width: 375,
  height: 812,
});

Client options:

const client = new BrowserGrab("bg_live_xxx", {
  retries: 3,        // retry on 5xx errors (default: 2)
  timeoutMs: 60_000, // per-request timeout in ms (default: 90000)
  baseUrl: "...",    // override API base URL
});

Error Handling

All API errors throw a BrowserGrabError with machine-readable fields.

import BrowserGrab, { BrowserGrabError } from "browsergrab";

const client = new BrowserGrab("bg_live_xxx");

try {
  const result = await client.screenshot({ url: "https://example.com" });
  console.log(result.url);
} catch (err) {
  if (err instanceof BrowserGrabError) {
    console.error(err.message);  // "Monthly quota exceeded (15/15 screenshots used...)"
    console.error(err.code);     // "quota_exceeded"
    console.error(err.status);   // 429
    console.error(err.charged);  // false — no credit used
  }
}

The SDK retries automatically on 5xx server errors with exponential backoff. 4xx errors are not retried since they represent caller mistakes.

Chrome Extension

The BrowserGrab Chrome extension lets you screenshot any tab with a single keyboard shortcut. Captures are sent to your BrowserGrab account and stored using your default settings — no copy-paste, no API calls to write.

Installation

Setup

Using the Keyboard Shortcut

Press Alt+Shift+S on any https:// page to capture a screenshot.

You'll see a Capturing… notification while the screenshot processes, then a Screenshot Captured! notification with the result URL. Clicking the notification opens the image in a new tab.

You can also click the extension popup and hit Capture This Page to trigger a capture without using the keyboard.

The extension cannot capture Chrome internal pages (chrome://), the New Tab page, or the Chrome Web Store — only regular http:// and https:// URLs.

Postman Collection

Every endpoint pre-wired with example bodies and expected responses. The fastest way to explore the API without writing any code.

The collection includes: Basic screenshot, all options, full page, mobile viewport, wait for animations, bulk screenshots (multiple URLs), Super features (retina + dark mode + block ads), base64 response, and Google Drive storage — each as a ready-to-run request.

Plans & Limits

Failed captures (DNS errors, blank pages, invalid URLs) are never charged against your quota. You only pay for successful screenshots.