Getting Started

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 edge network, so captures are fast from anywhere in the world. Store results on BrowserGrab's CDN, save directly to Google Drive, or receive the raw image as base64 in the response.

Quick Start#

Get your first screenshot in under a minute:

The API

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

Parameters#

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

Core — all plans

Super & Pro plan only

Bulk Screenshots#

Capture up to 20 URLs in a single API call. Each URL counts as one credit. The entire batch is quota-checked upfront — if you don't have enough credits the whole request is rejected.

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

{
  "success": true,
  "count": 3,
  "captured": 2,
  "failed": 1,
  "results": [
    {
      "url": "https://example.com",
      "success": true,
      "data": { "url": "https://pub-....r2.dev/...", "format": "png" },
      "charged": true
    },
    {
      "url": "https://bad-url.xyz",
      "success": false,
      "error": "page_load_failed",
      "message": "DNS lookup failed",
      "charged": false
    }
  ]
}

Storage Options#

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

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 to 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 whenever 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. Contact us for a custom plan if you need more.

SDK

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

yarn add 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..."
    console.error(err.code);     // "quota_exceeded"
    console.error(err.status);   // 429
    console.error(err.charged);  // false — no credit used
  }
}

Chrome Extension

Chrome Extension#

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

Installation#

Setup#

Keyboard Shortcut#

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

You'll see a Capturing… notification while processing, then a Screenshot Captured! notification with the result URL. Click it to open the image in a new tab.

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

Reference

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, animated wait, bulk screenshots, Super features (retina + dark mode + ad blocking), base64 response, and Google Drive storage — each as a ready-to-run request.

Plans & Limits#