crawlforge-browser-sessions

CrawlForge Browser Sessions

Drive a real browser across several calls. browser_session keeps one page — its cookies, its login, whatever it has already clicked — alive between calls, so you can look at the page, act, and look again, instead of guessing a whole chain of CSS selectors for a page you have never seen.

When to use

• Log in once, then read several pages behind the login → session.
• You do not know what is on the page yet — observe, then act → session.
• A flow that spans more than one tool call (wizard, filters, pagination, multi-step form) → session.
• A known, fixed action chain on one page → scrape_with_actions instead: one call, 5 credits, browser closed for you (see crawlforge-batch-automation).
• A page that renders without interaction → scrape (2 credits, see crawlforge-web-scraping).

The loop

open → snapshot → act on the refs → (snapshot again after a navigation) → read → close.

{ "tool": "browser_session", "params": { "operation": "open", "url": "https://app.example.com/login" } }

Returns a sessionId every later call passes as session_id, plus expiresAt and idleExpiresAt.

{ "tool": "browser_session", "params": { "operation": "snapshot", "session_id": "<id>" } }

Returns an accessibility tree with a stable ref on every interactive element:

[document] "Sign in"
  @e1 [textbox] "Email"
  @e2 [textbox] "Password"
  @e3 [button] "Sign in"

Act on those refs — a ref goes in selector, exactly where a CSS selector would:

{
  "tool": "browser_session",
  "params": {
    "operation": "act",
    "session_id": "<id>",
    "actions": [
      { "type": "type", "selector": "@e1", "text": "[email protected]" },
      { "type": "type", "selector": "@e2", "text": "hunter2" },
      { "type": "click", "selector": "@e3" },
      { "type": "wait", "duration": 2000 }
    ]
  }
}

actions is the same array scrape_with_actions takes: wait, click, type, press, scroll, select, hover, navigate, screenshot, snapshot, executeJavaScript. 1–20 per call; continue_on_error: true keeps going past a failed one.