Taking screenshots

This guide will show you how to take screenshots using the ScreenshotBuddy API.

Make sure your have read the quickstart guide. It will help you understand how to authenticate and make requests to the API.

Options

  • Name
    url
    Type
    string
    Description

    The URL of the page to render. It must start with http:// or https://, be at most 2048 characters long, and point at a publicly reachable host. Private, loopback and internal addresses are refused.

  • Name
    fullPage
    Type
    boolean
    Description

    Whether to capture the entire scrollable page instead of just the viewport. Defaults to false. Screenshots only; sending it with pdf is rejected, because a PDF always prints the whole document.

  • Name
    pdf
    Type
    boolean
    Description

    Set this to true to render a PDF instead of an image. It changes which other parameters are accepted, so see creating PDFs for the options that belong to that mode. Defaults to false.

  • Name
    format
    Type
    string
    Description

    The image format to return. Possible values are png, jpeg and webp. Defaults to png. Screenshots only; sending it with pdf is rejected. Use paperFormat to set the paper size of a PDF.

  • Name
    quality
    Type
    integer
    Description

    The quality of the image, between 1 and 100. It applies to lossy formats only, so format has to be jpeg or webp; sending it with png is rejected. Screenshots only; sending it with pdf is rejected.

  • Name
    width
    Type
    number
    Description

    The viewport width of a screenshot, or the paper width of a PDF, between 1 and 10000. Must be used together with height. For a PDF it overrides paperFormat and is read in the unit set by marginUnit.

  • Name
    height
    Type
    number
    Description

    The viewport height of a screenshot, or the paper height of a PDF, between 1 and 10000. Must be used together with width. For a PDF it overrides paperFormat and is read in the unit set by marginUnit.

  • Name
    scale
    Type
    integer
    Description

    In this mode, between 1 and 3. The scale of the rendering, between 1 and 3 for screenshots and between 0.1 and 2 for PDFs. Screenshots take whole numbers only, because the browser renders at whole device scale factors; PDFs take fractions. Defaults to 1. A value outside the range of the mode you are in is rejected.

  • Name
    delay
    Type
    integer
    Description

    How long to wait before capturing, in milliseconds, between 0 and 10000. Useful for pages that animate on load. Screenshots only; sending it with pdf is rejected, because the PDF renderer has no way to wait a fixed amount of time before it prints.

  • Name
    selector
    Type
    string
    Description

    A CSS selector. Only the first element that matches it is captured, instead of the page. At most 512 characters, and it may not contain single quotes, backslashes or control characters, so write attribute selectors with double quotes: a[href="/pricing"]. It chooses what to capture, so it cannot be combined with a clip region or with fullPage. Screenshots only; sending it with pdf is rejected.

  • Name
    clipX
    Type
    integer
    Description

    The distance from the left edge of the page to the region to capture, in pixels, between 0 and 10000. All four clip parameters (clipX, clipY, clipWidth, clipHeight) have to be set together. A clip region chooses what to capture, so it cannot be combined with selector or with fullPage. Screenshots only; sending it with pdf is rejected.

  • Name
    clipY
    Type
    integer
    Description

    The distance from the top edge of the page to the region to capture, in pixels, between 0 and 10000. Set it together with the other three clip parameters. Screenshots only; sending it with pdf is rejected.

  • Name
    clipWidth
    Type
    integer
    Description

    The width of the region to capture, in pixels, between 1 and 10000. Set it together with the other three clip parameters. Screenshots only; sending it with pdf is rejected.

  • Name
    clipHeight
    Type
    integer
    Description

    The height of the region to capture, in pixels, between 1 and 10000. Set it together with the other three clip parameters. Screenshots only; sending it with pdf is rejected.

  • Name
    omitBackground
    Type
    boolean
    Description

    Whether to render the page background transparent. Defaults to false. The format has to be able to hold transparency, so png or webp; sending it with jpeg is rejected rather than answered with a black background. Screenshots only; sending it with pdf is rejected.

  • Name
    waitForSelector
    Type
    string
    Description

    A CSS selector to wait for before capturing. The render continues once an element matching it exists. At most 512 characters, and under the same character restriction as selector: no single quotes, backslashes or control characters. Screenshots only; sending it with pdf is rejected.

  • Name
    waitUntil
    Type
    string
    Description

    The load event to wait for before capturing. Possible values are load, domcontentloaded, networkidle0 (no network connections for half a second) and networkidle2 (at most two). Defaults to networkidle2. Screenshots only; sending it with pdf is rejected.

  • Name
    cache
    Type
    boolean
    Description

    Whether an identical repeat of this request may be answered with the rendering we already made, and whether this rendering is kept for the next one. Defaults to true. A cached answer costs no credit, says so with X-Cache: HIT, and is counted against the account's cached-answer limit rather than against its renders; send cache=0 to render the page again, which costs a credit and a render slot as any render does. Entries belong to your own account. See caching for the whole picture.

  • Name
    cacheTtl
    Type
    integer
    Description

    How long the rendering is kept, in seconds, between 60 and 2592000 (thirty days). Defaults to 86400. Sending it with cache=0 is rejected, because there is no lifetime to set on a rendering that is not being kept.

What the target answered

A login wall renders. So does a 404 page, and a "too many requests" notice. The capture comes back as a crisp 200 with a real image in it, because that is genuinely what the page served, and nothing about the file itself says it is not the page you had in mind.

A screenshot answer therefore carries X-Target-Status: the status the page itself answered while we were loading it, which is a different thing from the status of our response to you. A rendered 404 page is a 200 from us carrying X-Target-Status: 404. Read it before you store a capture, and you will not quietly fill a bucket with pictures of a sign-in form.

A 4xx or 5xx target still costs a credit. We loaded the page and rendered what the server served, which is the work you asked for, and capturing an error page on purpose is a perfectly ordinary thing to want. The header is there so you can tell the two apart, not so you can be refunded for one of them.

A challenge page is the case the header cannot flag for you. A bot check, Cloudflare's "checking your browser" interstitial or anything shaped like it, is usually served as a 200, so X-Target-Status: 200 is a truthful answer about a page that is not the one you meant. A consent wall or a cookie banner covering the content is the same shape. Nothing failed when a capture comes back as a picture of a challenge: the site served that to us because we arrived as automated traffic, and the render is billed like any other. delay and waitForSelector help when the interstitial clears on its own; when it does not, there is nothing you can send that gets us past it, because the API carries neither your credentials nor your cookies. A login wall that answers a real 401 or 403 at least says so in the header.

The header is absent when we were not told a status, and absent means not known rather than 200. PDFs never carry it: the renderer reports nothing at all about the page behind a PDF render. An element capture, one that names a selector, carries none either, and for a close cousin of that reason: the one renderer endpoint that can capture a single element is the one that says nothing about the page it loaded. Neither do captures we cached before this header existed, until they lapse and are rendered again.

Try these options in the playground

The most common options on this page are controls in the playground. Change the viewport, switch the image type, and choose what the capture covers: the viewport, the whole page, one element named by a CSS selector, or a pixel region. The result appears next to the code that produces it. The options with no control of their own, waitForSelector and omitBackground among them, you add to the query string of the generated snippet yourself.

Open the playground