Browser Requests are our first main product and allow you to send the Gaffa API a URL and a list of actions you want to be carried out, including any outputs you want from the page. We'll carry out the request on our cloud browsers and return you the response with no need to worry about proxies, IP rotation, web automation frameworks and scaling.

There's absolutely zero configuration needed and you can interact with Gaffa from any program that can send web requests. We think it's by far the simplest way to automate simple web tasks and the good news is, we're just getting started and have much more planned.

Example request

Running a new browser request is as simple as sending the following POST body to our endpoint. Below, you can see the url (our demo site) and a list of actions which instruct Gaffa to wait for a table to load and print the page to PDF.

{
  "url": "https://demo.gaffa.dev/simulate/table?loadTime=3&rowCount=20",
  "proxy_location": null,
  "async": false,
  "max_cache_age": 0,
  "max_media_bandwidth": null,
  "settings": {
    "record_request": false,
    "actions": [
      {
        "type": "wait",
        "selector": "table"
      },
      {
        "type": "print",
        "size": "A4",
        "margin": 20,
        "orientation": "portrait"
      }
    ]
  }
}

Proxy servers

Gaffa makes proxying your traffic through a global network of residential proxies super simple. Setting proxy_location in your request will allow you to utilize one of our partner third party proxy services to gain local access to a site.

Not setting a proxy_location will mean the request does not use a proxy server and will use a generic datacenter IP.

Available Locations

IP Types

Currently all our IP addresses are residential IP addresses which are procured through reputable third parties.

IP Rotation

IP rotation is an essential part of any web data, scraping or automation task. In Gaffa, each browser request is treated as unique. We regularly rotate the IP addresses used so you should assume that each request will be carried out from a different IP address from the last.

Restrictions

Whilst we'll do our best to provide access to as wide a range of sites as possible we may have to restrict access to certain sites to prevent abuse of our service or of other services. Our proxy partners may also enforce restrictions on certain sites and categories of sites which we don't have any control over.

Caching

When we were building Gaffa we noticed that a lot of pre-existing scraping tools don't allow users to easily share their scraped web data with each other, despite many users requesting the same web pages on the same sites. Not only is this a waste of a user's allowance, it also puts a burden on the site owners who are serving the same data to different users for the same purpose. Because of this in Gaffa we have created a service-wide cache.

How it works

When making a browser request you can provide a MaxCacheAge parameter which is a number in seconds equal or greater than 0. This values denotes the maximum age of data you would accept from the API. If another user of our service has requested the same URL with exactly the same parameters and actions as you in this chosen timeframe then the response will be returned to you immediately and the response will not be carried out on one of our browsers. If there are multiple identical requests in the given timeframe then the most recent will be returned. This will save you time waiting for the response, as well as credits, because requests returned from the cache don't use any bandwidth.

Screen Recording

By specifying record_request you can ask Gaffa to screen record your automation and return a video in the response allowing you to view the magic happening or to debug your automation.

Recording requests comes at an additional cost.

Max Media Bandwidth

If you are using Gaffa on a site with lots of images and videos and more interested in the text data on the page, you can cap how much data a page loads in MB using the max_media_bandwidth setting. This makes your automation faster and prevents spending credits on data you aren't interested in. With the max_media_bandwidth value set, Gaffa monitors data being downloaded by the page and when downloaded data exceeds the given number of MB, all further downloads of images or video will be cancelled. max_media_bandwidth defaults to null meaning downloads are not capped.

Time Limit

Using the setting time_limit caps the maximum running time of the request in milliseconds. If this time expires all incomplete actions will be cancelled and the request will return an error. This cap has to be less than the maximum request running time dictated by your plan and if not set, will default to this value.

Actions

We currently support ten different types of actions which you can read more about here.

Stealth

We believe your AI Agents should be able to use the internet exactly how humans would. Gaffa can help you get access to sites with some of the most challenging anti-bot restrictions using a combination of proxies, human-like behavior, captcha solving and a custom browser implementation. We handle and maintain all of that so you can focus on building your solution!

Examples

We've created a number of sample browser requests you can read about here or you can jump straight into the API Playground to start running them right now.

API Endpoints

Check out our API reference for more details about the endpoints available, particularly those you can use to query for past requests by id or status.

Type: block_dom_removals

This action will prevent the page from removing items from the page. This is useful if you are trying to scrape data from a Javascript-based web application that removes items from the page when they are out of view which can make grabbing data difficult.

Using this action will block DOM removals for the rest of the browser request.

Parameters

See universal parameters.

Usage

Capture the cookies of the current page

"actions": [
    {
      "type": "block_dom_removals"
    }
]

The following example is a request we've pre-built to show you Gaffa's capabilities against our demo site. You can run this request right now in the Gaffa API Playground.

Gaffa converts web pages to clean markdown, stripping away styling, scripts, and images. This optimizes content for LLM applications by reducing token usage while preserving essential information.

API Request

The request below uses the POST endpoint to open the demo site on the article simulator, wait for the article to load and then generate a markdown from the page's content which you can download for use in your program.

{
  "url": "https://demo.gaffa.dev/simulate/article?loadTime=3&paragraphs=10&images=3",
  "proxy_location": null,
  "async": false,
  "max_cache_age": 0,
  "settings": {
    "record_request": false,
    "actions": [
      {
        "type": "wait",
        "selector": "article"
      },
      {
        "type": "generate_markdown"
      }
    ]
  }
}

Actions

Response

Here's an example of the PDF returned by the request after waiting for the article to load.

Type: capture_cookies

This action will capture the browser cookies currently saved for the web page you are on and return them as a JSON object with key/values.

Parameters

See universal parameters.

Usage

Capture the cookies of the current page

"actions": [
    {
      "type": "capture_cookies"
    }
]

Type: capture_element

Returns the , essentially the contents, of a particular element on the page. This can be used when you are only interested in the contents of a particular element.

Parameters

See .

Usage

Click an element on the page

The following code will wait 1 second for the .page_contents element to appear and return an html file containg the div's innerHTML.

Type: capture_snapshot

This output type will return a HTML file which captures a static version of the page state. The page will load offline and can be saved to your local machine.

This will:

• Load and embed all images on the page.

• Embed all css files

Currently, Javascript will be disabled and interactivity might not worked as expected but this feature should be useful for preserving the page state as it was and allowing you to view it offline.

Parameters

See

Usage

The following captures the current section of the page currently visible in the browser.

Example Output

Here's an example that shows an offline snapshot of a site

The following example is a request we've pre-built to show you Gaffa's capabilities against our You can run this request right now in the .

Filling forms is tedious, Gaffa can be used to fill out a form in a human-like manner so you can spend time doing much more interesting things.

API Request

The request below uses the to open the demo site on the form simulator page with some sections pre-filled (for speed). After typing in the required information and clicking submit, Gaffa waits for the success dialog to show before returning a video of the interaction.

Actions

Response

Here's a video showing Gaffa filling out the page and waiting for the success modal.

Read More

Read more about screen recording here (TODO).

In the following pages you can view all the pre-built requests we've built to show what is possible with the Gaffa web automation API.

You can start using these in the once you've created an account.

Type: print

Request that the browser prints the page to a PDF.

Parameters

See universal parameters.

Usage

Print a page in landscape to PDF

The following JSON prints the page to a PDF in landscape with margins of 20px.

"actions": [
    {
        "type": "print",
        "page_size": "A4",
        "orientation": "landscape",
        "margin": 20
    }
]

Example Output

Type: capture_dom

This action will capture and return the raw dom of the site which you can then extract data from on your end.

For common AI scenarios you may find this returns too much data so we have provided a generate_simplified_dom action which distills the DOM to only the important elements.

Parameters

See universal parameters.

Usage

Capture the raw DOM of the current page

"actions": [
    {
      "type": "capture_dom"
    }
]

Example Output

Type: download_file

Request a copy of the most recent file viewed in the browser.

Parameters

See universal parameters.

Files Supported

Currently this only works with PDF files.

Usage

Download a copy of a PDF open in the Browser

The following waits 20s for a file to download and then returns it.

"actions": [
    {
        "type": "download_file",
        "timeout": 20000
    }
]

And the service responds with the file being in the action output:

"actions": [
      {
        "id": "act_VHhrUbXjZSaYCPTqbBYD4acCzzeFGH",
        "type": "download_file",
        "query": "download_file?continue_on_fail=false&timeout=20000",
        "timestamp": "2025-05-30T15:02:06.6615306Z",
        "output": "https://storage.gaffa.dev/brq/downloads/5845df07-3749-424e-9c64-9602be19a857.pdf"
      }
    ]

Type: type

Request that the browser type a particular bit of text into a field.

Parameters

See universal parameters.

Usage

Type into a text box

The following action will type into a particular text field.

"actions": [
      {
            "name": "type",
            "selector": "#postform-text",
            "text": "Hello world!"
      }
]

Wait for an element to appear before typing

The following code will wait a maximum of 10 seconds for the email input to appear in the field and then type in the provided email.

"actions": [
      {
         "name": "type",
         "selector": "form input[name="email"]",
         "text": "test@test.com"
         "timeout": 10000
      }
]

The following example is a request we've pre-built to show you Gaffa's capabilities against our demo site. You can run this request right now in the Gaffa API Playground.

Gaffa automates infinite scrolling on dynamic pages like e-commerce storefronts. Set a duration, and Gaffa will capture all content as it scrolls. Each session can be recorded as a video for playback, letting you debug or review the interaction.

API Request

The request below uses the POST endpoint to open the demo site on the ecommerce site simulator with an infinitely scrolling storefront. It will wait for and dismiss a dialog box, wait for a product to load and then scroll down the page for a maximum of 20 seconds - if new items load it will keep scrolling.

{
  "url": "https://demo.gaffa.dev/simulate/ecommerce?loadTime=3&showModal=true&modalDelay=0&itemCount=infinite",
  "proxy_location": null,
  "async": false,
  "max_cache_age": 0,
  "settings": {
    "record_request": true,
    "actions": [
      {
        "type": "wait",
        "selector": "div[role=\"dialog\"]",
        "timeout": 10000
      },
      {
        "type": "click",
        "selector": "[data-testid=\"accept-all-button\"]"
      },
      {
        "type": "wait",
        "selector": "[data-testid^=\"product-1\"]",
        "timeout": 5000
      },
      {
        "type": "scroll",
        "percentage": 100,
        "max_scroll_time": 20000
      }
    ]
  }
}

Actions

Response

Here's a video showing Gaffa scrolling the page for 20 seconds as more items load.

Read More

Read more about screen recording here. (TODO)

The following example is a request we've pre-built to show you Gaffa's capabilities against our demo site. You can run this request right now in the Gaffa API Playground.

Gaffa's print to PDF feature allows you to export web pages as PDF files easily. Unlike the standard "Print to PDF" in your local browser, Gaffa's feature waits for specific items to load, uses proxies, and scales with your product's growth. Enhance your customer experience and streamline your PDF export process

API Request

The request below uses the POST endpoint to open the demo site on the table page, wait for the table to load and then print the webpage to a PDF in size A4 with a margin of 20 and using the portrait orientation.

{
  "url": "https://demo.gaffa.dev/simulate/table?loadTime=3&rowCount=20",
  "proxy_location": null,
  "async": false,
  "max_cache_age": 0,
  "settings": {
    "record_request": false,
    "actions": [
      {
        "type": "wait",
        "selector": "table"
      },
      {
        "type": "print",
        "size": "A4",
        "margin": 20,
        "orientation": "portrait"
      }
    ]
  }
}

Actions

Read the full documentation for these actions here.

Response

Here's an example of the PDF returned by the request after waiting for the table to load.

Type: parse_table

Finds a table on the page with a given selector and then converts the table data into a JSON object.

This action first fins the table headers and converts them into property names by converting them to lower case and replacing non-alphanumeric characters with underscores. It then processes each table row and for each cell is extracts the contents and saves a value. At the moment, all values will be string types.

Parameters

See .

Usage

Extract a table on the page

The following code will wait 1 second for the .large_table element to appear and return a JSON file with the headers and rows converted.

Type: generate_markdown

The markdown output format can export the data of the page (an article, table etc.) in a human and LLM readable format which removes unnecessary styling data and other "junk" that is only relevant for the site to work properly.

Gaffa exports with comments removed and unknown tags ignored.

Parameters

See .

Usage

The following converts the current page to markdown:

Example Output

Type: generate_simplified_dom

When you're looking at the DOM of a web page, there's a lot of unnecessary data that can be discarded if you are only interested in the page's elements or looking to export the data into a LLM. The generate_simplified_dom output format processes the HTML in the following way:

• Removes all links in the head

• Removes all script nodes and links to scripts

• Removes all style nodes

• Remove style attributes from all elements

• Remove all links to stylesheets

• Remove all noscript elements outside of the body

• Finds all hrefs with query strings and removes the query strings

• Important meta tags are kept, all others are removed

• Remove all alternate links

• Remove all SVG paths

• Remove empty text nodes and excessive spacing

Parameters

See universal parameters.

Usage

The following JSON captures the DOM of the page and simplifies it.

"actions": [
    {
        "type": "generate_simplified_dom"
    }
]

Example Output

Type: capture_screenshot

Takes a screenshot of the current page. You can choose to take a full screen screenshot showing the whole page or just the current view.

Parameters

See .

Usage

The following captures the current section of the page currently visible in the browser.

Example Output

An example screenshot in fullscreen mode.

The following example is a request we've pre-built to show you Gaffa's capabilities against our You can run this request right now in the .

Gaffa can also capture screenshots at any point during your interaction for use in your app or just to work out exactly was being shown at a given point in time. You can capture just what is shown as if you were looking at the screen or the full height of the page.

API Request

The request below uses the to open the demo site on the ecommerce page with 20 items, wait for and dismiss the dialog, scroll to the bottom of the page and capture a full height screenshot.

Actions

Response

The export full height screenshot of the page showing all items.

Type: click

Request that the browser clicks a particular element on the page.

Parameters

See .

Usage

Click an element on the page

The following code will wait 1 second and then continue with the next action, if provided.

Wait for a particular element to appear

The following code will wait for the logo to appear for a maximum of 5 seconds and it will continue with the list of actions

Type: parse_json

Use AI to parse web content from text into a pre-defined data schema and return it as a JSON object.

This feature currently works for online PDFs and web page text.

Parameters

See universal parameters.

Pricing

The credits this action uses depends on the model used. Here are the current supported models and their pricing:

Type: wait

Request that the browser waits a given amount of time or for a particular item to appear on the page.

Parameters

See universal parameters.

Usage

Wait for a particular amount of time

The following code will wait 1 second and then continue with the next action, if provided.

"actions": [
      {
        "name": "wait",
        "time": 1000,
      }
]

Wait for a particular element to appear

The following code will wait for a table to appear on the page for a maximum of 5 seconds. If the table has not appeared after 5 seconds the next action will be executed, if provided.

"actions": [
      {
        "name": "wait",
        "selector": "table",
        "timeout": 5000,
        "continueOnFail": true
      }
]

When making a Browser Request you can specify a list of actions you wish for us to carry out on the requested web page. These actions conform to the following format:

{
    "type": "", //the type of the action
    //other params follow as key value pairs
    "key": value //string, number etc. 
}

Universal Parameters

All actions have the following parameters:

Action Execution

Actions are carried out in the order they are submitted. Every action type has a continue_on_fail parameter which defaults to false, this means that if any action fails the execution of the browser request ends and an error will be returned. Setting continue_on_fail to true ensures that all actions are carried out, regardless of previous action results and an error will not be returned.

Custom Id

As shown above, you can submit a customId with each action you submit to the API. We'll include this Id in the outputs from the browser request so you can find a certain action's output and/or status easily in the response.

Response Format

When a browser request has completed, information on an action's execution

{
    "id": "", //a unique id given to the action by Gaffa
    "type": "capture_screenshot", //the type of the action
    "query": "", //a representation of the action in querystring format
    "timestamp": "", //the UTC timestamp the action was executed
    "output": "" //if the action has an output you will find a url for this here,
    "error": "" //if the requesst fails the error message will be returned here
}

Supported Actions

The Gaffa API supports the following actions detailed below. Click the "read more" buttons to read more information about each type.

Actions without outputs

Actions with outputs

Type: scroll

Request that the browser scrolls to a certain point on the page or, in the case of pages with infinite scrolling, scrolls for a particular amount of time.

Parameters

See .

Scroll Speed & Interval

Gaffa gives you a flexibility about how fast you scroll down the page which can be really useful to get around restrictions enforced by some sites which detect and limit fast scrolling. By experimenting with scroll_speed and interval you will be able to create the perfect scrolling action for your scenario. The speed settings are as follows:

• instant- the page will smoothly scroll to the desired position immediately, useful for sites with no rate limits or loading events caused by scroll actions.

• medium - human-like scrolling at a normal speed to the desired position. Gaffa will scroll in much the same way as you would using a mouse.

• slow- human-like scrolling at a very slow speed to the desired position. The speed is comparable to scrolling whilst reading a page.

intervalallows you to adjust the scroll speed further by inserting pauses between scroll events.

Wait Time

If wait_time is set to 0 and Gaffa arrives at the desired location then Gaffa will immediately mark the action as succeeded. However, if another value is set then the page will be monitored for the desired amount of time to check for further expansions. If, during this period, the page expands again then Gaffa will continue scrolling to the desired location and the wait will reset.

Usage

Scroll a particular percentage down the page

The following code will scroll half way down the page.

Scroll an infinitely scrolling webpage

The following code will scroll to the bottom of the page and then keep scrolling when new content loads for a maximum of 25 seconds, waiting 1 second for new content and scrolling at a slow pace with 1 second between scroll actions.