> 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/tips-and-best-practices.md). # Tips & Best Practices ### Tips #### Cost and speed * Set `max_media_bandwidth: 0` when you only want text. It blocks images and videos, keeps the page working, and reduces token usage by up to 43% on media-heavy sites. * Don't block media when you're screenshotting, printing or snapshotting. Those need the images. * Turn on `block_ads` on ad-heavy sites, and add a [`selector`](/docs/features/browser-requests/selectors.md) to [`generate_markdown`](/docs/features/browser-requests/actions/generate-markdown.md) and [`parse_json`](/docs/features/browser-requests/actions/parse-json.md) so you only pay for the part you want. * Use `max_cache_age` while you're developing, so re-running the same request doesn't cost you each time. #### Proxies * Leave `proxy_location` unset, and the request goes out from a data centre IP. Set it when a site blocks those, or serves different content by country. * Match the location to the content you want: us for `US` pricing, `fr` for French listings. * Assume a different IP on every request. They rotate, and proxies need a paid account. #### Reliability and debugging * Add up your action timeouts before setting `time_limit`. A single [`scroll`](/docs/features/browser-requests/actions/scroll.md) can run for 20 seconds. * Set `continue_on_fail: true` on optional actions, so one missing element doesn't cost you the whole request. * Add a [`capture_screenshot`](/docs/features/browser-requests/actions/capture-screenshot.md) between actions to find the step that broke. * Turn on `record_request` when something fails, and you can't tell why, then turn it back off. It costs extra. ### FAQs #### How do I reduce my Gaffa credit usage? Set `max_media_bandwidth: 0` to skip images and video, which saves up to 43% of tokens on media-heavy sites. Add a [`selector`](/docs/features/browser-requests/selectors.md) to narrow captures, and use [`parse_table`](/docs/features/browser-requests/actions/parse-table.md) instead of [`parse_json`](/docs/features/browser-requests/actions/parse-json.md) for tables. #### When should I not block media? Don't block it when you're capturing screenshots, printing to PDF, taking a snapshot, or checking anything visual. All of those need the images to actually load. #### Why does a site behave differently when I block media? Setting `max_media_bandwidth: 0` stops images from loading, and some sites read that as an ad blocker. Raise the limit to a small figure like 5 rather than blocking outright. #### How does caching work in Gaffa? Set `max_cache_age` in milliseconds to say how old a result you'll accept. If anyone has made the same request within that window, you get their response immediately, at no additional bandwidth cost. #### Why didn't my request come back from the cache? A cached result is returned only when the URL, parameters, and actions all match a previous request exactly. Any difference, however small, means the request runs fresh. #### When do I need to use a proxy? Use one when a site blocks datacenter traffic, or when content changes by country — regional pricing, local search results, geo-restricted pages. Set `proxy_location` to the country you want to appear from. #### Which proxy locations can I use? United States (us), Ireland (ie), Singapore (sg) and France (fr). All proxy IPs are residential addresses. Proxies require a paid account. #### **Can I keep the same IP across several requests?** No. Each request is treated separately, and IPs rotate, so assume a different address every time. If a task requires continuity, do it all in a single browser request. #### What does the time\_limit setting do? It caps the maximum duration the whole request can run, in milliseconds. When the time runs out, unfinished actions are cancelled and the request errors. It can't exceed your plan's maximum runtime. #### Why does my request keep timing out? Usually one slow action is using the whole budget, often a [`scroll`](/docs/features/browser-requests/actions/scroll.md) with a long `max_scroll_time` or a [`wait`](/docs/features/browser-requests/actions/wait.md) for an element that never appears. Check those before raising the limit. #### How do I debug a browser request that isn't working? Turn on `record_request` to watch it back as video, add [`screenshots`](/docs/features/browser-requests/actions/capture-screenshot.md) between actions to find the failing step, and run a [`capture_dom`](/docs/features/browser-requests/actions/capture-dom.md) to confirm your selectors exist on the page. #### Why did my request return an error partway through? By default, one failed action stops everything after it. Set `continue_on_fail: true` on actions that are allowed to fail, so the rest still run and you keep the results. --- # 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/tips-and-best-practices.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.