Name: Website Screenshot API: ShotPulse URL to Image
Brand: vatpulse
SKU: api-vatpulse-shotpulse
Availability: InStock
Author: API Market

VatPulse

# ShotPulse API

## Overview

The ShotPulse API turns any public web page into an image. You send a URL and the response body is the screenshot itself, as PNG, JPEG or WebP. There is one operation, `/screenshot`, offered in two forms: `GET` takes every option as a query parameter, which is handy for quick tests and image links, and `POST` takes the same options as a JSON object, which is easier from code and lets you pass `hide` as an array. Both accept the same 19 options: the page URL, one of 8 device presets or a custom viewport and pixel ratio, viewport or full-page capture, capture of a single element by CSS selector, output format and quality, wait conditions (a load event, a CSS selector or a fixed delay), best-effort dark mode, ad and tracker blocking, cookie-banner blocking, hiding elements, a custom user agent, and cache control.

It is built for developers who need page images inside their own products: link previews and Open Graph images, thumbnails for directories and CRMs, visual monitoring and archiving, QA and regression snapshots, and SEO or competitor reports. A successful call returns raw image bytes with a `Content-Type` of `image/png`, `image/jpeg` or `image/webp`, so you can save the body straight to a file or upload it to storage. Two response headers tell you how the image was produced: `X-Cache` is `HIT` when it came from the cache and `MISS` when it was freshly rendered, and `X-Render-Ms` gives the browser render time in milliseconds. Errors come back as JSON in the form `{"error": {"code": "...", "message": "..."}}`.

## Features

*   **2 endpoints, 1 operation**: `GET /screenshot` with query parameters and `POST /screenshot` with a JSON body, with the same options and the same image response.
*   **Simple input**: Only `url` is required. `https://` is added when the scheme is missing, and URLs up to 2,048 characters are accepted.
*   **Device presets**: `desktop` (the default, 1280x800), `desktop_hd`, `laptop`, `macbook_retina`, `ipad`, `iphone`, `iphone_se` and `android`. Each preset sets the viewport, pixel ratio, mobile flag and user agent.
*   **Custom viewport**: Set `width` (240 to 1920), `height` (240 to 2160) and `scale` (pixel ratio 1 to 3) to override the preset.
*   **Capture modes**: The visible viewport, the full scrollable page (`full_page`), or one element only (`selector`).
*   **Output formats**: PNG, JPEG or WebP, with `quality` from 1 to 100 for JPEG and WebP (default 80).
*   **Wait control**: Choose the load event with `wait_until`, wait for a visible element with `wait_for` (up to 10 seconds), or add a fixed `delay` of up to 10,000 ms for animations and lazy content.
*   **Clean captures**: Block common ad and tracking networks (`block_ads`), block common consent platforms and cookie banners (`block_cookie_banners`), and hide up to 10 elements by CSS selector (`hide`).
*   **Dark mode**: Best-effort dark rendering using the site's own `prefers-color-scheme: dark` styles and common dark-theme hooks.
*   **Built-in cache**: Identical requests within `cache_ttl` (24 hours by default, up to 7 days) are served from cache. Use `fresh=true` to force a new render.
*   **Method**: Each page is loaded and rendered in a browser on the provider's side. Only public http(s) pages are captured; private, loopback, link-local and cloud-metadata addresses are refused, including through redirects.
*   **Rate limit**: 1 request per second on every plan.

## Use Cases

*   **Link previews and OG images**: Generate a preview image for any URL a user shares in your app.
*   **Website thumbnails**: Show a picture of each site in a directory, CRM or bookmark manager.
*   **Visual monitoring and archiving**: Capture pages on a schedule to keep a visual record or spot changes.
*   **QA and regression snapshots**: Capture pages at desktop and mobile sizes after each deploy and compare them.
*   **Mobile previews**: See how a page looks on an iPhone, iPad or Android device without a device lab.
*   **SEO and competitor reports**: Add full-page captures of landing pages to client or competitor reports.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/vatpulse/shotpulse
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Capture a screenshot (query parameters)

Loads the page at `url`, renders it with the options you pass, and returns the image bytes. Every option is a query parameter, and booleans accept `true`, `false`, `1` or `0`. URL-encode the `url` value and any CSS selectors.

**Method:** `GET`

**Endpoint:** `/screenshot`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | query | Page to capture. http(s) only; `https://` is added when the scheme is missing. Private, loopback, link-local and cloud-metadata addresses are refused, including via redirects. | string | Yes | - | 2,048 characters |
| `device` | query | Device preset that sets viewport, pixel ratio, mobile flag and user agent. One of `desktop`, `desktop_hd`, `laptop`, `macbook_retina`, `ipad`, `iphone`, `iphone_se`, `android`. `width`, `height` and `scale` override it. | string | No | `desktop` (1280x800) | - |
| `width` | query | Viewport width in CSS pixels. Minimum 240. | integer | No | From `device` | 1920 |
| `height` | query | Viewport height in CSS pixels. This is the image height unless `full_page` is set. Minimum 240. | integer | No | From `device` | 2160 |
| `scale` | query | Device pixel ratio (`2` = retina). Minimum 1. width x height x scale² must stay under about 9.3 megapixels. | number | No | From `device` | 3 |
| `full_page` | query | Capture the full scrollable page instead of the viewport. | boolean | No | `false` | - |
| `format` | query | Image format: `png`, `jpeg` or `webp`. `jpg` is accepted as an alias for `jpeg`. | string | No | `png` | - |
| `quality` | query | JPEG or WebP quality. Minimum 1. Not allowed with `png`. | integer | No | `80` | 100 |
| `delay` | query | Extra wait in milliseconds after the page has loaded, for animations and lazy content. | integer | No | `0` | 10000 |
| `wait_for` | query | CSS selector to wait for (visible) before capturing, for up to 10 seconds. | string | No | - | 200 characters |
| `wait_until` | query | Navigation event that counts as loaded: `load`, `domcontentloaded`, `networkidle0` or `networkidle2`. | string | No | `networkidle2` | - |
| `selector` | query | Capture only the element that matches this CSS selector. Cannot be combined with `full_page`. | string | No | - | 200 characters |
| `dark_mode` | query | Best-effort dark mode: applies the site's `prefers-color-scheme: dark` styles and common dark-theme hooks (`class="dark"`, `data-theme="dark"`). Sites without dark styles look unchanged. | boolean | No | `false` | - |
| `block_ads` | query | Block requests to common ad and tracking networks and hide common ad slots. | boolean | No | `false` | - |
| `block_cookie_banners` | query | Block common consent-management scripts (OneTrust, Cookiebot, Quantcast, Didomi, Usercentrics and others) and hide typical cookie banners. | boolean | No | `false` | - |
| `hide` | query | Comma-separated CSS selectors of elements to hide. | string | No | - | 10 selectors |
| `user_agent` | query | Custom User-Agent string. | string | No | - | 300 characters |
| `cache_ttl` | query | How long the result is cached, in seconds. `0` means do not cache; any other value must be at least 60. Identical requests within the TTL are served from cache. | integer | No | `86400` | 604800 |
| `fresh` | query | Ignore any cached copy and render again. The new result is cached. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/vatpulse/shotpulse/screenshot?url=https%3A%2F%2Fexample.com&format=png" \
  -H "x-api-market-key: YOUR_API_KEY" \
  --output example.png
```

**Example Response (200 OK):**

The response body is the screenshot image itself with `Content-Type: image/png`; in our test this request returned an 89,909-byte PNG of example.com in about 1.1 seconds.

#### 2. Capture a screenshot (JSON body)

Takes the same options as the `GET` endpoint as a JSON object and returns the image bytes. Use it when you build requests in code, when selectors would be awkward to URL-encode, or when you want to pass `hide` as an array. Unknown fields are rejected.

**Method:** `POST`

**Endpoint:** `/screenshot`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | body | Page to capture. http(s) only; `https://` is added when the scheme is missing. Private, loopback, link-local and cloud-metadata addresses are refused, including via redirects. | string | Yes | - | 2,048 characters |
| `device` | body | Device preset that sets viewport, pixel ratio, mobile flag and user agent. One of `desktop`, `desktop_hd`, `laptop`, `macbook_retina`, `ipad`, `iphone`, `iphone_se`, `android`. `width`, `height` and `scale` override it. | string | No | `desktop` (1280x800) | - |
| `width` | body | Viewport width in CSS pixels. Minimum 240. | integer | No | From `device` | 1920 |
| `height` | body | Viewport height in CSS pixels. This is the image height unless `full_page` is set. Minimum 240. | integer | No | From `device` | 2160 |
| `scale` | body | Device pixel ratio (`2` = retina). Minimum 1. width x height x scale² must stay under about 9.3 megapixels. | number | No | From `device` | 3 |
| `full_page` | body | Capture the full scrollable page instead of the viewport. | boolean | No | `false` | - |
| `format` | body | Image format: `png`, `jpeg` or `webp`. `jpg` is accepted as an alias for `jpeg`. | string | No | `png` | - |
| `quality` | body | JPEG or WebP quality. Minimum 1. Not allowed with `png`. | integer | No | `80` | 100 |
| `delay` | body | Extra wait in milliseconds after the page has loaded, for animations and lazy content. | integer | No | `0` | 10000 |
| `wait_for` | body | CSS selector to wait for (visible) before capturing, for up to 10 seconds. | string | No | - | 200 characters |
| `wait_until` | body | Navigation event that counts as loaded: `load`, `domcontentloaded`, `networkidle0` or `networkidle2`. | string | No | `networkidle2` | - |
| `selector` | body | Capture only the element that matches this CSS selector. Cannot be combined with `full_page`. | string | No | - | 200 characters |
| `dark_mode` | body | Best-effort dark mode: applies the site's `prefers-color-scheme: dark` styles and common dark-theme hooks (`class="dark"`, `data-theme="dark"`). Sites without dark styles look unchanged. | boolean | No | `false` | - |
| `block_ads` | body | Block requests to common ad and tracking networks and hide common ad slots. | boolean | No | `false` | - |
| `block_cookie_banners` | body | Block common consent-management scripts (OneTrust, Cookiebot, Quantcast, Didomi, Usercentrics and others) and hide typical cookie banners. | boolean | No | `false` | - |
| `hide` | body | CSS selectors of elements to hide, either as a comma-separated string or as an array of strings (each up to 200 characters). | string or array | No | - | 10 selectors |
| `user_agent` | body | Custom User-Agent string. | string | No | - | 300 characters |
| `cache_ttl` | body | How long the result is cached, in seconds. `0` means do not cache; any other value must be at least 60. Identical requests within the TTL are served from cache. | integer | No | `86400` | 604800 |
| `fresh` | body | Ignore any cached copy and render again. The new result is cached. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/vatpulse/shotpulse/screenshot" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com",
    "device": "iphone",
    "format": "jpeg",
    "full_page": false,
    "block_cookie_banners": true
  }' \
  --output github-iphone.jpg
```

**Example Response (200 OK):**

The response body is the screenshot image itself with `Content-Type: image/jpeg`; in our test this request returned a 162,904-byte JPEG of github.com at the iPhone preset in about 11.5 seconds.

## Status Codes

Successful calls return the image. All error responses are JSON with an `error` object that holds a machine-readable `code` and a `message`.

| Code | Status | Description |
|---|---|---|
| 200 | OK | The screenshot was captured. The body is the image in the requested format, and `X-Cache` says whether it was served from cache. |
| 400 | Bad Request | A parameter is invalid (for example `quality` with `png`, or `selector` together with `full_page`), the URL is invalid, or the URL points to a private or internal address. |
| 401 | Unauthorized | The `x-api-market-key` value is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The path does not exist. Check that you are calling `/screenshot` under the base URL. |
| 422 | Unprocessable Entity | The page could not be loaded (DNS failure, connection or TLS error), the `selector` matched nothing (`selector_not_found`), or the image was over the size limit (`image_too_large`). |
| 429 | Too Many Requests | You went over 1 request per second, you have used all the calls in your plan, or the provider's per-minute abuse protection was triggered (`rate_limited`). Check the `Retry-After` header. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | The renderer failed (`render_failed`). Retry the request. |
| 503 | Service Unavailable | The renderers are busy (`busy`) or the day's rendering capacity is used up (`capacity_exhausted`). Retry after the number of seconds in the `Retry-After` header. Cached screenshots keep working. |
| 504 | Gateway Timeout | The page did not finish rendering in time (`render_timeout`). Try a lighter `wait_until` such as `load`, or remove `wait_for`. |

## Rate Limits

The Free Trial, Starter and Growth plans each allow 1 request per second. They include 100, 1,500 and 8,000 calls respectively, and every successful screenshot counts as one call, whether it was freshly rendered or served from cache. Requests above 1 per second, or after the plan's calls are used up, return `429 Too Many Requests`. Send requests one after another rather than in parallel, back off before retrying, and honour any `Retry-After` header. The provider also applies a per-minute abuse-protection limit, reported in the `X-RateLimit-Limit` and `X-RateLimit-Remaining` response headers. Fresh renders take several seconds: in our tests a desktop capture of example.com took about 1.1 seconds and an iPhone capture of github.com about 11.5 seconds, so set a client timeout of 60 seconds or more. Cached repeats of the same request return much faster.

## FAQ

**Should I use GET or POST?**

They take the same options and return the same image. `GET` is convenient for quick tests and for building image URLs. `POST` with a JSON body is easier from code, avoids URL-encoding CSS selectors, and lets you send `hide` as an array.

**How long does a screenshot take?**

It depends on the page. In our tests example.com took about 1.1 seconds and github.com at the iPhone preset took about 11.5 seconds. Pages that load a lot of scripts or wait on `networkidle0` take longer. Set a client timeout of 60 seconds or more. A repeat of an identical request within `cache_ttl` is served from cache and returns much faster, with `X-Cache: HIT`.

**How does the cache work, and is my image stored?**

Results are cached for `cache_ttl` seconds, 86,400 (24 hours) by default and up to 604,800 (7 days). An identical request within that time returns the cached image. Set `fresh=true` to force a new render, or `cache_ttl=0` to stop the result from being cached. According to the provider, the image is only kept in this cache.

**Why did I get 503 `busy` or `capacity_exhausted`?**

The renderers are temporarily full or the day's rendering capacity has been used. Wait for the number of seconds in the `Retry-After` header and try again. Cached screenshots keep working during this time.

**Can I capture localhost or pages on a private network?**

No. Only public http(s) pages can be captured. Private, loopback, link-local and cloud-metadata addresses are refused with `400`, including when a public URL redirects to one of them.

**Why does a WebP full-page capture of a long page fail?**

The provider notes that WebP images are limited to 16,383 pixels on a side. Use `format=jpeg` for long full-page captures. Very large captures can also return `422` with `image_too_large`, and width x height x scale² must stay under about 9.3 megapixels.

**How do I get a clean screenshot without banners and ads?**

Set `block_cookie_banners=true` and `block_ads=true`. For anything still in the way, such as a chat widget or a sticky header, pass its CSS selector in `hide`. If the page loads content late, add `wait_for` with a selector that appears when the content is ready, or a short `delay`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Website screenshot API that turns any public URL into a PNG, JPEG or WebP image, with full page capture, 8 device presets, dark mode and cookie banner blocking.

Website Screenshot API: ShotPulse URL to Image