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

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

The following endpoint creates a browser request and either runs it synchronously or returns immediately with an ID so you can check it status later using this endpoint.

The following endpoint allows you to query for multiple browser requests, either by status or a list of particular ids, submitting a request with neither of these will return all requests for your account.

The following endpoint allows you to query browser request for your account by ID.

The following endpoint allows you to delete a schema from your account.

The following endpoint allows you to update a data schema by ID.

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

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 endpoint allows you to describe a data schema for parsing an online PDF to JSON.

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

Usage

Capture the cookies of the current page

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.

Parameters

Usage

The following converts the current page to markdown:

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

Example Output

Type: capture_element

Parameters

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.

"actions": [
    {
      "type": "capture_element",
      "selector": ".page_contents",
      "timeout": 1000
    }
]

Type: json_parse

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

Currently this feature only works with online PDFs but we are working to expand it to webpages.

Parameters

Pricing

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

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

{
  "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: type

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

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
      }
]

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

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.

"actions": [
    {
      "type": "parse_table",
      "selector": ".large_table",
      "timeout": 1000
    }
]

Type: click

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

Parameters

Usage

Click an element on the page

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

"actions": [
    {
      "type": "click",
      "selector": "a.header__logo"
    }
]

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

"actions": [
      {
        "type": "wait",
        "selector": "a.header__logo",
          "timeout": 5000,
          "continueOnFail": true
      }
]

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

Usage

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

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

Example Output

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

{
  "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_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

Usage

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

"actions": [
    {
        "type": "capture_screenshot",
        "size": "view"
    }
]

Example Output

An example screenshot in fullscreen mode.

Type: print

Request that the browser prints the page to a PDF.

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: wait

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

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
      }
]

The following features are currently in beta and only avaialble to select users. If you are interested in trying out any of these features, please contact support and we can enable them for you.

JSON Data Parsing

Allows you to describe a JSON data schema for your data and then convert an online PDF into this data format using AI.

Endpoints:

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

{
  "url": "https://demo.gaffa.dev/simulate/form?loadTime=3&showModal=false&modalDelay=0&formType=address&firstName=John&lastName=Doe&address1=123%20Main%20Street&city=London&country=UK",
  "proxy_location": null,
  "async": false,
  "max_cache_age": 0,
  "settings": {
    "record_request": true,
    "actions": [
      {
        "type": "type",
        "selector": "#email",
        "text": "johndoe@example.com"
      },
      {
        "type": "type",
        "selector": "#state",
        "text": "CA"
      },
      {
        "type": "type",
        "selector": "#zipCode",
        "text": "12345"
      },
      {
        "type": "click",
        "selector": "button[type='submit']"
      },
      {
        "type": "wait",
        "selector": "[role=\"dialog\"] h2:has-text(\"Success!\")",
        "timeout": 10000
      }
    ]
  }
}

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).

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

{
  "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)

Creating Keys

Deleting Keys

If you are worried you have exposed your Gaffa API key or just want to periodically rotate your keys you can create another key and then delete your old keys. Deleted keys will immediately stop working for new requests to the API but past browser requests made using old keys will still be available.

Authenticating Requests

Our API is secured with a customer header X-API-Key whose value should be any current API key in your account. That's all you need to add to your request!

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.

The following endpoint allows you to list data schemas for your account in a paged list.

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

Actions

Response

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

Type: download_file

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

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.

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

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

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.

By the end of this guide, you’ll be able to:

• Render web pages using Gaffa’s API.

• Extract clean page content.

• Generate structured markdown suitable for LLM-based Q&A or summarization.

Prerequistes

1. Install Python 3.10 or newer.

2. Create a virtual environment

python -m venv venv && source venv/bin/activate

1. Install the required libraries

pip install requests openai

GAFFA_API_KEY=your_gaffa_api_key
OPENAI_API_KEY=your_openai_api_key

Convert a webpage to Markdown

import requests
import openai

GAFFA_API_KEY = os.getenv("GAFFA_API_KEY")
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Fetch the markdown content from Gaffa
def fetch_markdown_with_gaffa(url):
    payload = {
        "url": url,
        "proxy_location": None,
        "async": False,
        "max_cache_age": 0,
        "settings": {
            "record_request": False,
            "actions": [
                {
                    "type": "wait",
                    "selector": "article"
                },
                {
                    "type": "generate_markdown"
                }
            ]
        }
    }
   
    # Set the headers for the request
    headers = {
        "x-api-key": GAFFA_API_KEY,
        "Content-Type": "application/json"
    }
    # Make the POST request to the Gaffa API
    print("Calling Gaffa API to generate markdown...")
    response = requests.post("https://api.gaffa.dev/v1/browser/requests", json=payload, headers=headers)
    response.raise_for_status()
   
    # Extract the markdown URL from the response
    markdown_url = response.json()["data"]["actions"][1]["output"]
   
    # Fetch the markdown content from the generated URL
    print(f"📥 Fetching markdown from: {markdown_url}")
    markdown_response = requests.get(markdown_url)
    markdown_response.raise_for_status()
   
    return markdown_response.text

Ask questions using OpenAI

def ask_question(markdown, question):
    openai.api_key = OPENAI_API_KEY
    prompt = (
        f"You are an assistant helping analyze different webpages.\n\n"
        f"Markdown content:\n{markdown[:3000]}\n\n"
        f"Question: {question}\nAnswer as clearly as possible."
    )

    response = openai.ChatCompletion.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "user", "content": prompt}
        ]
    )
    return response.choices[0].message["content"]

The markdown becomes the model’s context, enabling accurate answers about the original web content.

User Interaction and Execution

Having defined the functions, we can now create a simple command-line interface that allows users to input a URL and ask questions about the content.

def main():
    url = input("Enter the URL of the article: ")
    try:
        markdown = fetch_markdown_with_gaffa(url)
        print("\n✅ Markdown successfully retrieved from Gaffa.\n")

        while True:
            question = input("Ask a question about the content (or type 'exit'): ")
            if question.lower() == "exit":
                break
            answer = ask_question(markdown, question)
            print(f"\n💬 Answer: {answer}\n")

    except Exception as e:
        print(f"⚠️ Error: {e}")

 if __name__ == "__main__":
    main()

Full Script

Running the Script

To run the script, simply execute it in your terminal:

python your_script_name.py

With your script running, you can enter any URL of any web page, and the script will fetch the markdown content and allow you to ask questions about it.