GET /v1/screenshot

GET /v1/screenshot is the screenshot API as a URL. Put the options in the query string and the response is the image itself, so the link works anywhere a browser or crawler loads an image: <img src>, og:image, Markdown, a spreadsheet. It accepts the common options under flat names. For everything else, use POST /v1/screenshot. Both are part of the API documentation.

GET https://api.renderscreenshot.com/v1/screenshot?url=...&preset=og_card

Authentication

Query parameters

Each name maps to a field of the POST body. The parameters overview gives the full POST list.

Waiting for a selector, injected scripts and styles, cookies, headers, target authentication, element capture and resizing have no GET name. Send those with POST.

Build the URL with an encoder

The target URL is itself a URL, so it must be encoded as a value. Let a library do it. All three builders below print the same query string. Tested on 2026-10-15 with Node 22.18, Python 3.14 and Ruby 4.0. We parsed each result with the same query parser the API uses and got the full target URL back.

Node.js

const params = new URLSearchParams({
  url: 'https://example.com/search?q=dark mode&page=2#results',
  preset: 'og_card',
  format: 'webp',
  block_cookies: 'true',
  api_key: process.env.RS_API_KEY, // server-side only; use a signed URL in public HTML
});
console.log(`https://api.renderscreenshot.com/v1/screenshot?${params}`);

Python

import os
from urllib.parse import urlencode

params = {
    'url': 'https://example.com/search?q=dark mode&page=2#results',
    'preset': 'og_card',
    'format': 'webp',
    'block_cookies': 'true',
    'api_key': os.environ['RS_API_KEY'],  # server-side only; use a signed URL in public HTML
}
print('https://api.renderscreenshot.com/v1/screenshot?' + urlencode(params))

Ruby

require 'uri'

params = {
  url: 'https://example.com/search?q=dark mode&page=2#results',
  preset: 'og_card',
  format: 'webp',
  block_cookies: 'true',
  api_key: ENV.fetch('RS_API_KEY') # server-side only; use a signed URL in public HTML
}
puts "https://api.renderscreenshot.com/v1/screenshot?#{URI.encode_www_form(params)}"

curl

curl --get https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer $RS_API_KEY" \
  --data-urlencode 'url=https://example.com/search?q=dark mode&page=2#results' \
  -d preset=og_card -d format=webp \
  --output screenshot.webp

Encoding pitfalls

We parsed the unencoded version of the URL above the same way. The API saw the target https://example.com/search?q=dark mode, with no page=2, and no preset or api_key at all. These are the mistakes behind that result and a few quieter ones:

• & in the target splits it. Unencoded, &page=2 becomes a parameter of the API call, not of your page.
• # ends the query string. Browsers never send the fragment, so everything after # is lost, including any API parameters you put after the target.
• + means a space. A literal plus in the target, as in ?tags=a+b, must be sent as %2B.
• Booleans are words. Only true turns an option on. block_ads=1 or block_ads=yes is ignored without an error.
• Commas split hide and remove. A selector such as :is(.a, .b) is cut in two. Use POST with an array.
• Unknown formats are rejected. A format value outside png, jpeg, webp and pdf returns HTTP 400 with invalid_format.
• & in HTML attributes. Inside an <img src> or content="" attribute, write & as &. Browsers and crawlers decode it back. Template engines that escape output do this for you.
• Never edit a signed URL. Adding &format=webp after signing breaks the signature. Add every parameter before you sign.

The signed variant

A signed GET URL has the same parameters plus key_id (your rs_pub_ public key ID) and expires, sorted alphabetically, then signature: the HMAC-SHA256 of everything before it, keyed with your rs_secret_ key. Signed URLs authenticate only this endpoint (GET, or HEAD, with no body); they do not work for POST /v1/screenshot or any other endpoint.

https://api.renderscreenshot.com/v1/screenshot?expires=1792644628&key_id=rs_pub_...&preset=og_card&url=https%3A%2F%2Fexample.com%2Fblog%2Fhello-world&signature=5c0f...

<meta property="og:image" content="https://api.renderscreenshot.com/v1/screenshot?expires=1792644628&amp;key_id=rs_pub_...&amp;preset=og_card&amp;url=https%3A%2F%2Fexample.com%2Fblog%2Fhello-world&amp;signature=5c0f...">

Signing code in six languages is on the signed URLs page.

Response

By default the body is the image or PDF, with Content-Type set to match. Send Accept: application/json to get JSON with the CDN URL instead. The headers carry X-Credits-Remaining, X-Cache-URL and X-Request-Id. See response headers and caching.

Errors

In an <img> tag a failed request shows as a broken image, and the browser hides the reason. Open the same URL with curl to read it:

curl -i "https://api.renderscreenshot.com/v1/screenshot?url=example.com&api_key=$RS_API_KEY"

{
  "error": {
    "type": "validation_error",
    "code": "invalid_url",
    "message": "The URL 'example.com' is not a valid HTTP(S) URL",
    "param": "url",
    "retryable": false,
    "docs": "https://renderscreenshot.com/docs/errors/invalid-url"
  },
  "request_id": "7a2e4c10-93b5-4d6f-8e1a-0b9c3d5f7e21"
}

Examples

Full page, ads and cookie banners blocked, WebP:

https://api.renderscreenshot.com/v1/screenshot?url=https%3A%2F%2Fexample.com&full_page=true&block_ads=true&block_cookies=true&format=webp&api_key=rs_live_...

A4 PDF with backgrounds and 1 cm margins:

https://api.renderscreenshot.com/v1/screenshot?url=https%3A%2F%2Fexample.com&format=pdf&pdf_paper=a4&pdf_print_background=true&pdf_margin=1cm&api_key=rs_live_...

Dark mode in French, reuse a render from the last 24 hours if there is one:

https://api.renderscreenshot.com/v1/screenshot?url=https%3A%2F%2Fexample.com&dark_mode=true&locale=fr-FR&cache_available=true&api_key=rs_live_...

Last verified 2026-10-15 against the API's query parameter mapping.