Integration Recommendations & Best Practices

To get the most out of bro, we recommend following these guidelines and tips to optimize for performance, reliability and cost.

Batch related commands: Group sequential actions into a single POST /execute call. This dramatically reduces network round-trips and latency.
Graceful cleanup: Always shut down sessions explicitly when your task completes or fails (by using a finally block in python3, for ex). This frees up the worker immediately and prevents unnecessary billing for idle time.
Set client-side timeouts: Although bro uses smart long-polling, always set explicit client-side timeouts to prevent your integration from hanging indefinitely in case of network drops.

Choosing the right tool:
- Use manual commands when you know the exact action sequence and page layout. It's the fastest and cheapest approach.
- Use act when you need to interact with a page (like searching for something, filling a form, etc.).
- Use extract when you are already on the target page and just need to scrape structured JSON data.
Designing JSON Schemas:
- Extracting lists: If you want to extract a list or array of objects (like search results or a table), wrap your schema object in brackets []. Example: [{"title": "...", "price": "..."}].
- Provide rich context: Don't just provide empty strings or generic keys. Give the AI more context about the values you expect by adding short descriptions, data types, allowed values or classification criteria right inside the schema values. Example: {"status": "<'in_stock' or 'out_of_stock'>", "price": "<numeric float value without currency symbol>"}.
Cost optimization for AI:
- If you only need text data from a simple layout, consider setting vision: false in your extract parameters. It will rely purely on the text recognized by our OCR model (which is cheaper).
- Use viewport_max to restrict the AI's attention if the data you need is always at the top of the page (ignoring massive footers or unrelated content below).

Stateful workflows: Reuse the same session for multi-step workflows. bro maintains cookies, local storage and page state between commands.
Optimize proxy usage: Enable proxies only when encountering anti-bot protections. To save bandwidth costs, choose the most restrictive proxy_policy that still works for your target (e.g., html_only or extended instead of full). If a website protection is sever, switch back to full.
Billing snapshots: Fetch the session object via GET /sessions/{session_id} after expensive workflows to get the most up-to-date snapshot of your proxy and AI costs.