Browshot Getting Started: API Key & First Screenshot (2026)

Getting started overview

Integrating with the Browshot API involves a series of steps to ensure successful setup and execution of your first screenshot request. This guide provides a structured approach, starting from account registration and API key acquisition, through to making a basic API call. Browshot offers a RESTful interface for capturing website screenshots, allowing customization of browser settings, screen sizes, and the injection of custom CSS or JavaScript for tailored rendering environments. The process is designed to be straightforward, enabling developers to quickly incorporate automated screenshot functionality into their projects.

To begin, you will register for a Browshot account and locate your unique API key. This key authenticates your requests to the Browshot service. Following credential retrieval, you will construct and execute a simple API call using either a direct HTTP request or one of the official SDKs provided by Browshot. The objective is to generate a screenshot of a specified URL, confirming your setup is operational.

Quick Reference Steps

The following table summarizes the essential steps to get started with Browshot:

Create an account and get keys

To access the Browshot API, you must first register for an account. Browshot does not offer a free tier; therefore, account creation will involve selecting a Browshot pricing plan. Plans start at $9.99 per month for the Hobbyist tier, which includes 1,000 screenshots. During the sign-up process, you will provide necessary contact and billing information.

Once your account is successfully created and a plan is chosen, your unique API key will be provisioned. This key serves as your primary authentication credential for all API requests. The API key is typically found within your Browshot account dashboard or settings section. It is crucial to treat your API key as sensitive information, similar to a password, to prevent unauthorized access to your screenshot credits. Best practices for API key management include storing it securely and avoiding hardcoding it directly into client-side code that could be publicly exposed.

Your first request

After obtaining your API key, you can proceed to make your first request to the Browshot API. This example demonstrates a basic request to capture a screenshot of a specified URL using the GET method. The Browshot API is RESTful, meaning it uses standard HTTP methods and status codes, as outlined in the HTTP/1.1 Semantics and Content specification.

The core endpoint for creating a screenshot is https://api.browshot.com/api/v1/simple. You will append your API key and the target URL as query parameters.

Example: Basic Screenshot with cURL

Using cURL is a common way to test API endpoints directly from the command line:

curl "https://api.browshot.com/api/v1/simple?url=https://www.example.com&key=YOUR_API_KEY&instance_id=4&width=1280&height=1024"

In this example:

• url: The website you want to screenshot (e.g., https://www.example.com).
• key: Your unique Browshot API key. Replace YOUR_API_KEY with your actual key.
• instance_id: Specifies the browser instance to use. For initial testing, an instance_id like 4 (representing a common desktop browser) is often a good starting point. Consult the Browshot API reference for instance IDs.
• width: The desired width of the screenshot in pixels.
• height: The desired height of the screenshot in pixels.

Upon successful execution, the API will return a JSON response containing a URL to the generated screenshot. You can then access this URL in a web browser to view the screenshot.

Example: Python SDK

Browshot provides official SDKs for several languages, including Python. Using an SDK simplifies the process by abstracting HTTP request details.

import browshot

# Replace with your actual API key
API_KEY = "YOUR_API_KEY"

browshot_api = browshot.Browshot(API_KEY)

try:
    # Take a simple screenshot
    screenshot = browshot_api.simple_screenshot(
        url="https://www.example.com",
        instance_id=4,  # Example instance ID
        width=1280,
        height=1024
    )

    if screenshot and 'screenshot_url' in screenshot:
        print(f"Screenshot URL: {screenshot['screenshot_url']}")
    else:
        print("Failed to get screenshot URL.")

except browshot.BrowshotError as e:
    print(f"Browshot API Error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

To use the Python SDK, you first need to install it:

pip install browshot

This Python example initializes the Browshot client with your API key and then calls the simple_screenshot method with the required parameters. The response will contain the URL where the screenshot image is hosted.

Common next steps

After successfully generating your first screenshot, several common next steps can enhance your integration with Browshot:

1. Explore Advanced Options: The Browshot API offers extensive customization options beyond basic screenshots. You can experiment with parameters such as:
• delay: To wait a specified number of seconds before taking the screenshot, useful for pages with dynamic content.
• css: To inject custom CSS styles onto the page before rendering.
• javascript: To execute custom JavaScript code on the page.
• full_page: To capture the entire scrollable height of a webpage.
• quality: To adjust the output image quality.
• Different instance_id values: To render pages using various browser types and operating systems (e.g., mobile devices, specific browser versions). Refer to the Browshot API parameters documentation for a full list.
2. Handle Asynchronous Requests: For complex or high-volume screenshot tasks, Browshot offers an asynchronous API. This allows you to initiate a screenshot request and receive a callback (webhook) when the screenshot is ready, preventing your application from waiting for potentially long rendering times. Setting up webhooks for asynchronous processing is a common pattern for integrating services that involve processing delays.
3. Error Handling: Implement robust error handling in your application. The Browshot API returns standard HTTP status codes and detailed JSON error messages. Proper error handling allows your application to gracefully manage issues like invalid API keys, rate limits, or problems with the target URL.
4. Integrate with Storage: The screenshot URLs provided by Browshot are temporary. For persistent storage, you will need to download the images from these URLs and store them in your own infrastructure, such as Amazon S3 (see AWS S3 user guide) or Google Cloud Storage (see Google Cloud Storage documentation).
5. Monitor Usage: Regularly check your Browshot account dashboard to monitor API usage and ensure you stay within your plan's limits. This helps prevent service interruptions due to exceeding screenshot quotas.

Troubleshooting the first call

If your initial Browshot API call does not work as expected, consider the following troubleshooting steps:

• Invalid API Key: Double-check that you have copied your API key correctly from your Browshot account dashboard. Ensure there are no leading or trailing spaces. An invalid key typically results in an authentication error (e.g., HTTP 401 Unauthorized).
• Incorrect URL Formatting: Verify that the url parameter is correctly encoded and includes the full protocol (http:// or https://). Malformed URLs can lead to errors or blank screenshots.
• Rate Limiting: If you are making multiple requests in quick succession, you might be hitting rate limits. Check the Browshot documentation on rate limits and implement appropriate delays or exponential backoff in your code.
• Instance ID: Ensure the instance_id you are using is valid and available. While 4 is a common default, specific instances might be temporarily unavailable or require a higher-tier plan.
• Network Issues: Confirm that your environment has outbound internet access and is not blocked by a firewall from reaching api.browshot.com.
• Target Website Issues: The target website itself might be down, slow to load, or have anti-bot measures that prevent Browshot from rendering it correctly. Try screenshotting a different, known-good website (e.g., https://www.google.com) to isolate the issue.
• Check API Response: Always inspect the full API response, including HTTP status codes and any JSON error messages. These messages often provide specific details about what went wrong. For example, an HTTP 400 Bad Request usually indicates a problem with your request parameters.
• Consult Documentation: The official Browshot documentation is the most comprehensive resource for API parameters, error codes, and best practices. Reviewing the relevant sections can often resolve issues quickly.