> For the complete documentation index, see [llms.txt](https://gaffa.dev/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gaffa.dev/docs/features/browser-requests/actions.md). # Actions When [making a Browser Request](/docs/api-reference/post-v1-browser-requests.md), you can specify a list of actions you want us to perform on the requested web page. These actions conform to the following format: {% code overflow="wrap" fullWidth="false" %} ```json { "type": "", //the type of the action //other params follow as key-value pairs "key": value //string, number, etc. } ``` {% endcode %} ### Universal Parameters All actions have the following parameters:

Name	Type	Required	Description
`type`	`string`	true	The type name of the action.
`continue_on_fail`	`boolean`	false	Should execution of further actions continue or throw an error if this action fails. Default: `false`
`custom_id`	`string`	false	A custom_id to help you find the action in the response. Default: `null`

#### 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 the previous action's results, and an error will not be returned. #### Custom Id As shown above, you can submit a `custom_id` 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 {% code fullWidth="false" %} ```json { "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 request fails, the error message will be returned here } ``` {% endcode %} ## Choosing an action


I want to…	Use	Not
Send page content to an LLM	`generate_markdown`	`capture_dom` — too big and too noisy
Find selectors on a page I don't know	`generate_simplified_dom`	`generate_markdown` — it drops the structure you need
Work out why a selector isn't matching	`capture_dom`	`generate_simplified_dom` — it may have removed what you're looking for
Turn one HTML table into rows	`parse_table`	`parse_json` — you'd pay credits for something free, and it wouldn’t be deterministic
Pull structured data out of prose, a PDF, or a messy layout	`parse_json`	`parse_table` — it only reads <table> markup
Get the contents of one element I know about	`capture_element`	`capture_dom` — it returns the whole page
Show what a page looked like	`capture_screenshot`	`generate_markdown` — no visual record
Keep a copy of a page I can look at again later	`capture_snapshot`	`capture_screenshot` — you can't search an image
Turn a page into a PDF	`print`	`capture_snapshot` — that gives you HTML
Get a file the browser has open	`download_file`	`print` — it re-renders the page instead of taking the file
Capture several pages of results in one request	`loop`	Sending one request per page — you'd pay the page load each time \|

## 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

Type	Description	Read More
`block_dom_removals`	Prevents the page from removing elements from the DOM.	Block DOM Removals
`click`	Click on a given element	Click
`scroll`	Scroll to a particular point on the page or, in the case of pages with infinite scrolling, scroll until a given time has elapsed.	Scroll
`type`	Type the provided text into a given element	Type
`wait`	Wait for a given time to elapse or an element to appear on page before proceeding to the next action.	Wait

### Actions with outputs

Type	Description	Read More
`capture_cookies`	Save a JSON object of cookies for the current page	Capture Cookies
`capture_dom`	Export the raw DOM page data	DOM
`capture_screenshot`	Capture a screenshot of the web page	Screenshot
`capture_element`	Export the contents of a single element on the page	Capture Element
`capture_snapshot`	Create a completely static version of the web page which can be accessed offline	Snapshot
`download_file`	Download an online file using Gaffa	Download File
`generate_markdown`	Convert the page into markdown	Markdown
`generate_simplified_dom`	Generate a simplified version of the DOM	Simplified DOM
`parse_json`	Parse online data to a defined JSON schema	JSON Parsing
`parse_table`	Convert an HTML table into JSON rows	Parse Table
`print`	Print the web page to a PDF	Print

### Flow Actions

Type	Description	Read more
`loop`	Runs nested actions repeatedly until it reaches a limit, times out, or an action fails.	Loop

Tips

* Actions run in the order you list them, so put your capture actions last. * Set `continue_on_fail: true` on anything optional, like closing a cookie banner. Otherwise, a single failure halts the entire request. * Set a `custom_id` on each action so you can find its output in the response. * You don't need a [`wait`](/docs/features/browser-requests/actions/wait.md) before [`click`](/docs/features/browser-requests/actions/click.md), [`capture_element`](/docs/features/browser-requests/actions/capture-element.md) or [`parse_table`](/docs/features/browser-requests/actions/parse-table.md). They already wait for their own [`selector`](/docs/features/browser-requests/selectors.md). * Add a `selector` to [`generate_markdown`](/docs/features/browser-requests/actions/generate-markdown.md) or [`parse_json`](/docs/features/browser-requests/actions/parse-json.md) to reduce what you capture and what you pay for. * If you're not sure an action worked, add a [`capture_screenshot`](/docs/features/browser-requests/actions/capture-screenshot.md) after it. * Use [`loop`](/docs/features/browser-requests/actions/loop.md) when you need more than one page from a single request, rather than sending a request per page. * Inside a [`loop`](/docs/features/browser-requests/actions/loop.md), put capture actions before the action that navigates. Anything after a failing action is skipped for that pass.

***

FAQs

#### In what order do Gaffa actions run? Actions run one after another, in the order you list them in the actions array. #### How do I capture multiple pages in a single request? Use the [`loop`](/docs/features/browser-requests/actions/loop.md) action. It repeats a nested list of actions, so one request can page through search results or a numbered list. Loops can't be nested inside each other. #### What happens when a Gaffa action fails? The browser request stops and returns an error, and the remaining actions are skipped. Set `continue_on_fail: true` on that action if you want the rest to run anyway. Inside a [`loop`](/docs/features/browser-requests/actions/loop.md), a failure skips the rest of that iteration rather than ending the request, and the loop's `stop_on_fail` decides whether it exits or starts the next pass. #### How do I find the output of a specific action in the response? Give the action a `custom_id` when you send it. Gaffa returns that ID in the response, so you can look up the action's output without counting through the array. #### Can I use the same action twice in one request? Yes. Add it at each point where you need it — for example, a before-and-after screenshot of a click. Give each one a different `custom_id` so you can tell them apart. #### Which Gaffa actions cost extra credits? [`parse_json`](/docs/features/browser-requests/actions/parse-json.md) is the only one. It's billed on the tokens sent to and returned by the AI model. Keep costs down with `selector`, `input_token_cap` and `max_pages`.

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gaffa.dev/docs/features/browser-requests/actions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.