How to Send Thumbalizr Screenshots to Amazon S3

Short answer: Thumbalizr’s published Embed API documentation does not list an Amazon S3 hosting parameter. For a documented automatic screenshot-to-S3 workflow, use Browshot’s screenshot API with hosting=s3 and hosting_bucket. Browshot says it can upload the screenshot directly to your bucket without first downloading the image to your own server. Contact Browshot for its current S3 account setup and access instructions before relying on the workflow.

This distinction matters: Thumbalizr and Browshot have related product history, but the documented APIs are not interchangeable. Thumbalizr’s Embed API returns an image URL for embedding; Browshot documents the S3 hosting options described below. See Browshot API documentation and its automated S3 upload instructions.

1. Prepare the account and bucket

Create or use a Browshot API account and obtain its API key. Browshot API requests use the key parameter.
Create the destination S3 bucket, or choose a bucket you control. Record its exact bucket name and region for your own AWS operations.
Contact Browshot and request the current instructions for enabling uploads to your bucket. Its S3 page says to let them know you plan to use the feature so they can provide instructions.
Apply the vendor-specific access configuration Browshot supplies. Do not assume a generic IAM policy or ACL will work; the required setup depends on Browshot’s current upload method and your bucket settings.
Choose an object key convention before sending production captures. For example, use a stable page identifier and date in hosting_file so separate captures do not unintentionally overwrite each other.

AWS requires write permission to upload an object. Review AWS’s S3 upload documentation alongside the exact access instructions Browshot provides. Browshot specifically notes that bad bucket details or ACL configuration can cause upload errors.

2. Create a screenshot request with S3 hosting

The documented operation is /api/v1/screenshot/create. At minimum, send the target url, an instance_id, your key, and the S3 hosting settings. Pick an instance available to your account; the example uses instance 12 as a placeholder from Browshot’s API examples. Confirm the instance and account limits in your own Browshot account.

cURL

curl --get 'https://api.browshot.com/api/v1/screenshot/create' \
  --data-urlencode 'url=https://example.com/' \
  --data-urlencode 'instance_id=12' \
  --data-urlencode 'key=YOUR_BROWSHOT_API_KEY' \
  --data-urlencode 'hosting=s3' \
  --data-urlencode 'hosting_bucket=YOUR_BUCKET_NAME' \
  --data-urlencode 'hosting_file=screenshots/example-homepage.png' \
  --data-urlencode 'size=page' \
  --data-urlencode 'cache=0'

The API accepts GET or POST requests. For production systems, prefer a POST request if supported by your integration so secrets and long URLs are less likely to appear in URL logs. Protect the key either way. The API response is JSON; this request does not return the image bytes as its response.

Python

Install the dependency with python -m pip install requests. This runnable example submits the job and prints the JSON response:

import os
import requests

api_key = os.environ["BROWSHOT_API_KEY"]
params = {
    "url": "https://example.com/",
    "instance_id": 12,
    "key": api_key,
    "hosting": "s3",
    "hosting_bucket": "YOUR_BUCKET_NAME",
    "hosting_file": "screenshots/example-homepage.png",
    "size": "page",
    "cache": 0,
}

response = requests.get(
    "https://api.browshot.com/api/v1/screenshot/create",
    params=params,
    timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)

if result.get("status") == "error":
    raise RuntimeError(result.get("error", "Screenshot request failed"))

if result.get("status") == "in_process":
    print("Screenshot accepted; track its id through Browshot's screenshot info API.")
elif result.get("status") == "finished":
    print("Screenshot finished:", result)

Set BROWSHOT_API_KEY in the process environment rather than committing a real key. The request uses a 60-second HTTP timeout to bound the API call; screenshot completion can be asynchronous and is a separate state from the HTTP request finishing.

Node.js

This example uses the built-in fetch available in current Node.js versions. It submits the request and handles the JSON status:

const apiKey = process.env.BROWSHOT_API_KEY;
if (!apiKey) throw new Error("Set BROWSHOT_API_KEY first");

const params = new URLSearchParams({
  url: "https://example.com/",
  instance_id: "12",
  key: apiKey,
  hosting: "s3",
  hosting_bucket: "YOUR_BUCKET_NAME",
  hosting_file: "screenshots/example-homepage.png",
  size: "page",
  cache: "0",
});

const response = await fetch(
  `https://api.browshot.com/api/v1/screenshot/create?${params}`,
  { signal: AbortSignal.timeout(60_000) }
);
if (!response.ok) {
  throw new Error(`Browshot HTTP error: ${response.status} ${await response.text()}`);
}
const result = await response.json();
console.log(result);

if (result.status === "error") {
  throw new Error(result.error || "Screenshot request failed");
}
if (result.status === "in_process") {
  console.log(`Accepted as job ${result.id}; check screenshot info until it finishes.`);
} else if (result.status === "finished") {
  console.log("Screenshot finished:", result);
}

Because query parameters can be recorded by proxies and request logs, keep this server-side and redact the API key from logs. Do not put a Browshot API key in browser JavaScript or a public page.

3. Choose the stored image and capture settings

Parameter	Purpose	Notes
`url`	Page to capture	Required. URL-encode it when building a request.
`instance_id`	Browser instance used for capture	Required by screenshot/create. Confirm that the selected instance is available to your account.
`hosting=s3`	Enables S3 hosting	Documented Browshot hosting option.
`hosting_bucket`	Destination bucket name	Required for S3 hosting. Verify spelling and vendor-provided access setup.
`hosting_file`	Object file name/key	Optional. Set it when you need a predictable object name. Choose a unique key when preserving historical captures.
`hosting_width`, `hosting_height`	Maximum hosted thumbnail dimensions	Optional; use these when you want a thumbnail rather than only the full capture.
`hosting_scale`	Hosted thumbnail scale	Optional. The docs list it as a thumbnail setting; check the API documentation for the accepted values and behavior.
`hosting_headers`	Headers added to the S3 object	Optional. Use only documented values suitable for your bucket and delivery path.
`hosting_private`	Private hosting ACL behavior	Optional. Browshot documents this as setting `bucket-owner-full-control` instead of `public-read`. Confirm compatibility with your bucket’s ownership and ACL settings.
`size`	Capture viewport or full page	`screen` is the default; `page` requests page size.
`screen_width`, `screen_height`	Desktop viewport dimensions	Optional; documented ranges are 1–5000 for width and 1–10000 for height.
`delay`, `max_wait`	Control when capture happens	`delay` is 0–20 seconds, default 5; `max_wait` is 1–60 seconds, default disabled. Tune for pages that render content after load.
`cache`	Reuse a recent screenshot	Default cache duration is 24 hours. Use `cache=0` to request a fresh capture.

Other documented capture options include hide_popups, dark, strict_ssl, referer, post_data, cookie, script, script_inline, headers, and target for a CSS-selected element. Some options are limited to paid screenshots or certain browser types. Check the current parameter documentation before adding them. The S3 hosting parameters apply to screenshot requests and are separate from those capture settings.

4. Handle asynchronous completion and verify the object

A successful HTTP request means Browshot accepted the API request; it does not necessarily mean the browser capture and S3 upload have already finished. The documented examples show response statuses including in_process, finished, and error. When the response is in_process, retain the screenshot id and poll /api/v1/screenshot/info until the job reaches a terminal state, following the documented API response fields and rate guidance. The screenshot API also documents a hook notification URL for completion or failure; use it if you need event-driven processing, and make the receiver safe to handle retries.

Check the initial response for status and id.
If still processing, query the screenshot info endpoint for that ID until it reports finished or error.
On completion, inspect the response data and then verify the expected object exists in the configured bucket using your normal AWS tooling or application.
Test access separately. An object may exist but remain private; access depends on the bucket and object policy, ACL settings, and your chosen delivery method.
Record the job ID, requested object key, completion status, and error detail in your application logs, while redacting secrets.

Do not infer that an object is public because a screenshot job finished. Prefer private storage and controlled delivery when screenshots may contain sensitive page data.

5. Troubleshooting

Symptom	Likely cause	What to do
Thumbalizr response has no S3 object or hosting field	The published Thumbalizr Embed API does not document direct S3 hosting.	Use Browshot’s documented screenshot API and S3 options, or capture through Thumbalizr and upload the returned image yourself using your own storage code.
`Invalid key` or HTTP 403	Missing, misspelled, expired, or incorrectly supplied API key; malformed request.	Check the key in the Browshot account, encode parameters properly, and inspect the response error. Do not expose the key in client code.
Screenshot status is `error`	Capture failed, required input is invalid, or the account lacks required credits/instance access.	Read the returned error, verify URL and instance, and check account access and balance.
S3 upload error or no object appears	Incorrect bucket name or an access/ACL mismatch.	Confirm the exact bucket name and ask Browshot for its current bucket configuration steps. Check AWS permissions without substituting an unverified generic policy.
Job stays `in_process`	The screenshot has not reached a terminal state yet, or the application stopped checking.	Continue checking the screenshot info endpoint with bounded backoff, or configure the documented hook and handle retries.
Stored image is old	A cached capture was reused.	Set `cache=0` when a fresh screenshot is required, or choose an appropriate cache lifetime for your workload.
Screenshot misses late-loading content	The page renders important content after the capture timing point.	Adjust `delay` or `max_wait` and verify the resulting capture. Avoid unnecessarily long waits across every request.
Expected filename was not used	`hosting_file` was omitted, malformed, or your key convention differs from the service’s object naming behavior.	Set a simple explicit file name and verify it in the bucket. Ask Browshot to confirm any path or naming constraints.
Object exists but cannot be fetched	Private bucket/object settings or delivery permissions prevent access.	Check the intended access model and configure AWS delivery permissions separately. Do not make a bucket public simply to work around an upload issue.
HTTP client times out while the screenshot continues	The screenshot job can outlast a synchronous client timeout.	Use the asynchronous create/info pattern, set a bounded HTTP timeout, and continue tracking the returned job ID.

6. Performance, reliability, and cost considerations

Direct upload reduces your transfer work: Browshot describes uploading to S3 without downloading the finished image to your own server first. Your service still needs to track capture completion and handle failures.
Use cache deliberately: Browshot documents a default cache period of 24 hours and cache=0 for a new screenshot. Reuse is useful for repeated identical captures; disable it when page changes must appear immediately.
Make retries safe: Use deterministic job tracking and unique object keys if each run must be preserved. If a webhook is used, Browshot documents that notifications can be retried up to two times, so process duplicate notifications safely.
Separate capture failures from storage failures: Log the screenshot job status and confirm S3 object presence independently. This makes it easier to identify whether the browser job, S3 configuration, or downstream access path failed.
Budget both services: Browshot’s S3 feature page says automated uploads are free, but the screenshot API still uses the account’s screenshot plan/credits. AWS storage and requests are governed by your AWS account. The supplied documentation does not establish your specific Browshot plan price or AWS bill.
Do not assume public delivery: The documented hosting_private option affects ACL behavior. Choose a storage and delivery policy that fits the sensitivity of captured pages.

Or skip the browser setup

If your goal is to get a clean screenshot rather than specifically to store it through Browshot’s S3 integration, ScreenshotNeo is a website screenshot API and MCP server. It returns a screenshot or PDF from one GET request. See the ScreenshotNeo API documentation for parameters, and then store the returned image in S3 using your own AWS upload code.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/ -o shot.webp

ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Can Thumbalizr’s Embed API upload directly to my S3 bucket?

Its published Embed API documentation does not list an S3 hosting parameter. The documented direct hosting workflow in the research for this guide is Browshot’s screenshot API.

Does Browshot need my application to download the image first?

No. Browshot describes a workflow where it uploads the screenshot or generated thumbnail to your bucket directly.

Does a successful screenshot response prove the object is publicly accessible?

No. Capture completion, object existence, and object access are separate checks. Verify each according to your bucket’s policy.

Can I name the S3 object myself?

Browshot documents the optional hosting_file parameter for the object name. Confirm any naming constraints with the service if your application relies on a particular key format.

Is the S3 upload feature immediately enabled for every account?

The feature page asks users to contact Browshot for instructions. It does not establish an onboarding response time, so confirm access before building a production dependency on it.