Browser API

Run browser-backed scrapes and manage Team-scoped Sessions and persistent Profiles.

Quick start

Use browser scrape when a page needs rendering. Public browser controls are limited to wait, iframe, shadow DOM, and virtual scroll behavior.

API base https://kieapi.com

curl -X POST "https://kieapi.com/v1/browser/scrape" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H "Idempotency-Key: browser-example-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog",
    "browser": {
      "wait_for_selector": ".post-card",
      "process_iframes": true,
      "flatten_shadow_dom": true,
      "virtual_scroll": {
        "container_selector": ".feed",
        "scroll_count": 5,
        "scroll_by": "page_height"
      }
    },
    "extraction": {
      "type": "json_css",
      "schema": {
        "name": "blog_posts",
        "base_selector": ".post-card",
        "fields": [
          { "name": "title", "selector": "h2", "type": "text", "transform": "strip" },
          { "name": "path", "selector": "a", "type": "attribute", "attribute": "href" }
        ]
      },
      "computed_fields": [
        { "name": "url", "operation": "template", "template": "https://example.com{path}" }
      ]
    }
  }'

Authentication

Use a bearer token.

Team administrators manage API keys in Team Settings. Each key keeps its Team and billing scope when its creator leaves or switches Teams. Keys cannot manage members, billing or other keys.

Response shape

Rendered result

Page content and structured items returned after DICloak-backed browser execution completes.

Safe browser controls

browser.wait_for_selector, process_iframes, flatten_shadow_dom, and virtual_scroll map to human_behavior without exposing arbitrary JavaScript, cookies, storage state, proxy URLs, user agents, or DICloak profile IDs.

Structured extraction

Crawl4AI executes the same allowlisted schema used by Extract and Crawl over rendered HTML.

Sessions and Profiles

Create idempotent Team-billed Sessions with direct, managed residential, dedicated static IP or saved custom proxy routes. Profiles save the network selection for later Sessions. Dynamic proxy_usage reports confirmed response bytes and charges separately from Browser time; observer loss ends the Session. Mint one-time controller tickets and manage provider-backed Profiles without exposing provider IDs, nodes, credentials, cookies, or raw state.

Browser runtime pricing

120 Credits/hour ($0.12/hour), charged on actual active seconds and rounded up at 1 Credit per 30 seconds. Full TTL is reserved and unused Credits are released. Idle Profiles are free. Per-Team Profile / Session limits: Free 5/1, Starter 20/2, Scale 100/4, Enterprise 200/4.

Recovery and retry semantics

Profile names are Spider-only display metadata. If-Match updates are atomic; Session idempotency replay precedes new-resource checks. Accepted startup survives HTTP disconnect with its original 60-second deadline. Runtime billing is capped at Session expiry using the original price snapshot; handshake failures release the controller so a fresh ticket can reconnect.

Diagnostics

Browser scrape returns PublicPageResult.diagnostics; use result.diagnostics.adaptive_extraction for selector memory / adaptive extraction diagnostics, result.diagnostics.browser_debug for sanitized browser debug capture counts, result.diagnostics.browser_failure for sanitized browser failure category/stage diagnostics, and result.diagnostics.content_quality for content quality diagnostics.

Reference

Endpoint reference

OpenAPI-backed details for browser scrape, Sessions, persistent Profiles, scoped connection tickets, and error responses.

OpenAPI endpoint details

Interactive schemas, request bodies, response objects, and public error contracts load here.