| API Playground | Start experimenting with the Gaffa API right now. | https://gaffa.dev/dashboard/playground |
| Get Started | The simple steps to get you started using Gaffa in your apps. | Get Started |
| API Reference | Explore the API and docs for the finer details | API Reference |
| Print to PDF | Export a web page to PDF and wait for elements to load with the Gaffa API. | Export Web Page to PDF |
| Convert to Markdown | Export a web page to markdown format - useful feeding into LLM apps. | Convert Web Page to Markdown |
| Infinitely Scroll | Scroll the bottom of a page that infinitely loads items and record the interaction. | Infinitely Scroll an E-commerce Site |
| Capture Screenshot | Interact with a page and capture the a screenshot of the whole page. | Capture a Full-Height Screenshot |
| Form Completion | Fill out a form in a human-like way and record the interaction | Automated Form Filling |
| Selector | What it does |
|---|---|
:visible | Matches only elements that are actually rendered and visible. |
:nth-match(selector, n) | The nth match across the whole page, unlike :nth-child which counts within one parent. |
:light() | Matches only the normal page DOM, ignoring content inside web components. |
>> | Chains selector types together, for example css=... >> xpath=.... |
| 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 |
| 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 | |
| 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 |
| 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 |
| Type | Description | Read more |
|---|---|---|
loop | Runs nested actions repeatedly until it reaches a limit, times out, or an action fails. | Loop |
block_dom_removal actioncapture_cookies actioncature_dom actioncapture_screenshot action| Name | Type | Required | Description |
|---|---|---|---|
size | string | false | The area of the page to capture in the screenshot. Default: viewAccepted: ["view", "fullscreen"] |
capture_element action| Name | Type | Required | Description |
|---|---|---|---|
selector | string | true | The selector that defines the element whose contents you want to capture. |
timeout | integer | false | The maximum amount of time the browser should wait for the element defined by the selector to appear. Default: 5000 (5s) |
| Name | Type | Required | Description |
|---|---|---|---|
selector | string | true | The selector that defines the page element that the browser should click on. |
timeout | integer | false | The maximum amount of time the browser should wait for the element defined by the selector to appear. Default: 5000 (5s) |
download_file action| Name | Type | Required | Description |
|---|---|---|---|
timeout | integer | false | The maximum amount of time the browser should wait for a file to download. Default: 5,000 (5s) |
generate_markdown| Name | Type | Required | Description |
|---|---|---|---|
selector | string | false | The selector that defines an element you want to generate markdown from. This is useful if you are only interested in the contents of a certain element. |
output_type | string | false | Should the action output be saved to a file where a URL will be returned or should the output be included directly in the request. Default: fileAccepted: ["file", "inline"] |
generate_simplified_domloop action| Name | Type | Required | Description |
|---|---|---|---|
actions | action[] | true | The ordered list of actions to run on every iteration. Nested actions are written exactly like the actions in your request and support the full set of action types, with the exception of loop itself. |
max_iterations | integer | false | The upper bound on how many times the loop can run. Also acts as the iteration count when iterations is not set.Default: 10 Min: 1 Max: 1,000 |
iterations | integer | false | A fixed number of times to run the nested actions. If you send this alongside max_iterations, the loop runs whichever of the two is lower. Min: 1Max: 100 |
timeout | integer | false | The maximum amount of time the whole loop can run before it is cancelled, in milliseconds. This covers every iteration combined, not each one. Default: 20,000 (20s) |
stop_on_fail | boolean | false | Whether the loop should exit when a nested action fails. A nested action with its own continue_on_fail set to true does not trigger this.Default: true |
continue_on_fail | boolean | false | Whether the loop itself is reported as a success when it exits early. Set it to false to pass the failure up to the parent action list, or true to treat an early exit as a clean finish.Default: false |
Nested action continue_on_fail | Loop stop_on_fail | Loop continue_on_fail | Result |
true | either | either | The failure is ignored. The rest of the iteration runs and the loop continues. |
false | true | false | The rest of the iteration is skipped. The loop exits as failed. The parent action list stops unless it has continue_on_fail: true. |
false | true | true | The rest of the iteration is skipped. The loop exits successfully. The parent action list continues. |
false | false | either | The rest of the iteration is skipped. The loop moves to the next iteration and eventually succeeds. |
| Scenario | Suggested value |
|---|---|
| Known, fixed page count | The exact count |
| Unknown but bounded site | A conservative upper bound, for example 50 to 100 |
| Open-ended, as a safety net | 1,000, combined with a tight timeout |
print action| Name | Type | Required | Description |
|---|---|---|---|
size | string | false | The size of paper the page should be printed to. Default: A4Accepted: ["A4"] |
margin | integer | false | The margin of the page in pixels when the page is printed to PDF. Default: 20 |
orientation | string | false | The orientation of the printed PDF page. Default: portrait Accepted: ["portrait", "landscape"] |
| false |
parse_json| Name | Type | Required | Description |
|---|---|---|---|
data_schema_id | string | true | The id of the data schema you have defined that you want to transform the content into. You must provide a data_schema or data_schema_id with your request. |
data_schema | json | true | A JSON object describing the data_schema you want to transform the content into. You must provide a |
instruction | string | false | A custom instruction, in addition to any detail you have added to the data schema, that you want to include with this particular parse. |
model | string | false | The AI model you wish to use to parse the content into JSON. Default: gpt-4o-miniAccepted: ["gpt-4o-mini"] |
input_token_cap | int | false | The max number of source input tokens that will be passed to the AI model to parse. This can be used to prevent unnecessary credit usage. If your source input is longer than the token cap, it will be abbreviated. Default: 1,000,000 |
selector | string | false | The selector that defines an element you want to parse the content of - this is useful if you are only interested in the contents of a certain element. |
output_type | string | false | Should the action output be saved to a file where a URL will be returned or should the parsed JSON object be included directly in the request. Default: fileAccepted: ["file", "inline"] |
max_pages | int | false | If you are parsing a PDF you can specify this parameter to limit the number of pages that are passed to the LLM. Default: no limit |
| Property | Type | Description |
|---|---|---|
description | string | Explains what data the schema extracts and provides context to help the AI model understand the extraction goal. Example: "Extract product details from this e-commerce product page" |
fields | array | Each field defines a piece of data to extract from the content. See field properties below. |
name | string | This identifies the schema and should clearly indicate what data it extracts. Example: "ProductInfo", "ArticleMetadata", "ContactForm" |
description | string | Include details about format, handling of missing values, or special cases. Example: |
fields | array | Required only for object and array types. |
name | string | Use clear, descriptive names that follow your preferred naming convention (e.g., snake_case or camelCase). Example: "product_name", "published_date", "author_email" |
type | string | Determines how the AI interprets and structures the extracted data. Must be one of the supported types below. |
parse_table| Name | Type | Required | Description |
|---|---|---|---|
selector | string | true | The selector that identifies the table you want to parse. |
timeout | integer | false | The maximum time in milliseconds to wait for the table to appear. Default: 5000 (5s) |
| Name | Type | Required | Description |
|---|---|---|---|
percentage | integer | true | How far down the page to scroll, as a target position rather than a distance. Scrolling only moves forward — see the tip above. Range: [0 - 100] |
wait_time | integer | false | After arriving at the desired scroll location, the time Gaffa should monitor for changes in the page height before marking the action as successful. Read more below. Default: 0 |
max_scroll_time | integer | false | The maximum amount of time the page should be scrolled for, in milliseconds. After this time passes, the action will be cancelled. This doesn't cause the action to fail. Default: 20,000 (20s) |
scroll_speed | string | false | The speed which the page should scroll to the desired point. You can read more about this below. Default: mediumAccepted: [ slow, medium, instant] |
interval | integer | false | The amount of time, in milliseconds, that scrolling should pause between scroll events. Read more about this below. Default: 0 |
timeout | integer | false | The maximum amount of time Gaffa will wait for the page to become scrollable Default: 0 |
selector | string | false | The selector that identifies the element to scroll. If not provided, the page body will be scrolled. |
| Cover image | ||
|---|---|---|
| How to Handle Infinite Scrolling and Dynamic Loading with Gaffa’s Scroll Action | https://gaffa.dev/blog/how-to-handle-infinite-scrolling-and-dynamic-loading-with-gaffas-scroll-action | scroll_illustration_1920x1080_V4.jpg |
type action| Name | Type | Required | Description |
|---|---|---|---|
selector | string | true | The selector that defines the text field where the browser should type. |
text | string | true | The text the browser should enter into the text field. |
wait action| Name | Type | Description |
|---|---|---|
time | integer | The time in milliseconds the browser should wait. |
selector | string | The selector for the element to wait for. You must provide a timeout when using selector. |
timeout | integer | The maximum time in milliseconds to wait for selector to appear. Default: 5,000 (5s). Required when using selector. |
Gaffa's full height screenshot
{
"data": {
"id": "smr_VQW4E66TdcQFZfCs6qavgdowPj3Bzk",
"url": "https://gaffa.dev",
"state": "completed",
"credit_usage": 1,
"from_cache": true,
"started_at": "2025-08-22T11:05:43.328175Z",
"completed_at": "2025-08-22T11:05:47.857941Z",
"running_time": "00:00:04.5297660",
"links": [
"https://gaffa.dev",
"https://gaffa.dev/about",
"https://gaffa.dev/blog",
"https://gaffa.dev/blog/convert-any-web-page-to-llm-ready-markdown-using-gaffa",
"https://gaffa.dev/blog/how-to-extract-and-simplify-a-webpage-dom-with-gaffa",
"https://gaffa.dev/blog/printing-webpages-to-pdf-html-to-pdf-using-gaffa",
"https://gaffa.dev/docs",
"https://gaffa.dev/docs/api-reference/api-authentication",
....and so on
],
"link_count": 52
}
}