API Reference

Getting Started

Go from zero to your first browser session in under a minute. All you need is an API key.

1. Get your API key

Sign up at browserbeam.com and create an API key from the dashboard.

2. Create a session and navigate to a page

Open your terminal and run:

curl -X POST https://api.browserbeam.com/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

from browserbeam import Browserbeam

client = Browserbeam(api_key="YOUR_API_KEY")
session = client.sessions.create(url="https://example.com")
print(session.session_id)  # ses_abc123
print(session.page.title)  # Example Domain

import Browserbeam from "@browserbeam/sdk";

const client = new Browserbeam({ apiKey: "YOUR_API_KEY" });
const session = await client.sessions.create({ url: "https://example.com" });
console.log(session.sessionId);  // ses_abc123
console.log(session.page.title);  // Example Domain

require "browserbeam"

client = Browserbeam::Client.new(api_key: "YOUR_API_KEY")
session = client.sessions.create(url: "https://example.com")
puts session.session_id  # ses_abc123
puts session.page.title  # Example Domain

3. Read the response

The response includes the page content as markdown, interactive elements with refs, and scroll position:

{
  "session_id": "ses_abc123",
  "expires_at": "2026-03-18T14:05:00Z",
  "request_id": "req_1a2b3c4d5e6f",
  "completed": 1,
  "page": {
    "url": "https://example.com",
    "title": "Example Domain",
    "stable": true,
    "markdown": {
      "content": "# Example Domain\n\nThis domain is for use in illustrative examples..."
    },
    "interactive_elements": [
      {"ref": "e1", "tag": "a", "role": "link", "label": "More information...", "in": "main"}
    ],
    "forms": [],
    "map": [
      {"section": "header", "selector": "header", "hint": "Example Domain (1 link)"},
      {"section": "main", "selector": "main", "hint": "Example Domain (1 link)"},
      {"section": "footer", "selector": "footer", "hint": "More information... (1 link)"}
    ],
    "changes": null,
    "scroll": {"y": 0, "height": 600, "viewport": 720, "percent": 100}
  },
  "media": [],
  "extraction": null,
  "blockers_dismissed": ["cookie_consent"],
  "error": null
}

4. Interact with the page

Use the element refs from the response to click, fill, or otherwise interact:

curl -X POST https://api.browserbeam.com/v1/sessions/ses_abc123/act \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"steps": [{"click": {"ref": "e1"}}]}'

session.click(ref="e1")
print(session.page.url)  # navigated to new page

await session.click({ ref: "e1" });
console.log(session.page.url);  // navigated to new page

session.click(ref: "e1")
puts session.page.url  # navigated to new page

5. Destroy the session

Always clean up when done. This frees resources and stops credit consumption:

curl -X DELETE https://api.browserbeam.com/v1/sessions/ses_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

client.sessions.destroy(session.session_id)  # 204 No Content

await client.sessions.destroy(session.sessionId);  // 204 No Content

client.sessions.destroy(session.session_id)  # 204 No Content

6. Next steps

Authentication

Every request requires an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from the dashboard.

Missing or invalid keys return 401:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

POST /v1/sessions

Create a browser session. Optionally navigate to a URL and execute steps in the same call.

curl -X POST https://api.browserbeam.com/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

from browserbeam import Browserbeam

client = Browserbeam(api_key="YOUR_API_KEY")
session = client.sessions.create(url="https://example.com")

import Browserbeam from "@browserbeam/sdk";

const client = new Browserbeam({ apiKey: "YOUR_API_KEY" });
const session = await client.sessions.create({ url: "https://example.com" });

require "browserbeam"

client = Browserbeam::Client.new(api_key: "YOUR_API_KEY")
session = client.sessions.create(url: "https://example.com")

{
  "url": "https://example.com"
}

{
  "session_id": "ses_abc123",
  "expires_at": "2026-03-18T14:05:00Z",
  "request_id": "req_1a2b3c4d5e6f",
  "completed": 1,
  "page": {
    "url": "https://example.com",
    "title": "Example Domain",
    "stable": true,
    "markdown": {
      "content": "# Example Domain\n\nThis domain is for use in illustrative examples..."
    },
    "interactive_elements": [
      {"ref": "e1", "tag": "a", "role": "link", "label": "More information...", "in": "main"}
    ],
    "forms": [],
    "map": [
      {"section": "header", "selector": "header", "hint": "Example Domain (1 link)"},
      {"section": "main", "selector": "main", "hint": "Example Domain (1 link)"},
      {"section": "footer", "selector": "footer", "hint": "More information... (1 link)"}
    ],
    "changes": null,
    "scroll": {"y": 0, "height": 600, "viewport": 720, "percent": 100}
  },
  "media": [],
  "extraction": null,
  "blockers_dismissed": ["cookie_consent"],
  "error": null
}

{
  "url": "https://example.com/login",
  "steps": [
    {
      "fill_form": {
        "fields": {"Email": "user@test.com", "Password": "secret"},
        "submit": true
      }
    },
    {"screenshot": {}},
    {"close": {}}
  ]
}

{
  "url": "https://example.com",
  "timeout": 600,
  "viewport": {"width": 1920, "height": 1080},
  "locale": "en-US",
  "timezone": "America/New_York",
  "block_resources": [],
  "auto_dismiss_blockers": true
}

GET /v1/sessions/:id

Get session status and metadata.

curl https://api.browserbeam.com/v1/sessions/ses_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

info = client.sessions.get(session.session_id)

const info = await client.sessions.get(session.sessionId);

info = client.sessions.get(session.session_id)

{
  "session_id": "ses_abc123",
  "status": "active",
  "started_at": "2026-03-18T13:55:00Z",
  "ended_at": null,
  "duration_seconds": null,
  "expires_at": "2026-03-18T14:00:00Z"
}

{
  "session_id": "ses_abc123",
  "status": "failed",
  "started_at": "2026-03-18T13:55:00Z",
  "ended_at": "2026-03-18T13:56:20Z",
  "duration_seconds": 80,
  "expires_at": "2026-03-18T14:00:00Z",
  "error_code": "access_denied",
  "error_message": "Page returned HTTP 403 — access denied or geo-restricted"
}

POST /v1/sessions/:id/act

Execute steps on an existing session. Steps run sequentially. On failure, execution stops and the error is returned alongside current page state. Auto-observe runs at the end.

curl -X POST https://api.browserbeam.com/v1/sessions/ses_abc123/act \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      {"fill": {"ref": "e1", "value": "search query"}},
      {"click": {"ref": "e3"}},
      {"screenshot": {}}
    ]
  }'

session.fill("search query", ref="e1")
session.click(ref="e3")
session.screenshot()

await session.fill({ ref: "e1", value: "search query" });
await session.click({ ref: "e3" });
await session.screenshot();

session.fill("search query", ref: "e1")
session.click(ref: "e3")
session.screenshot

{
  "steps": [
    {"fill": {"ref": "e1", "value": "search query"}},
    {"click": {"ref": "e3"}},
    {"screenshot": {}}
  ]
}

{
  "session_id": "ses_abc123",
  "expires_at": "2026-03-18T14:05:00Z",
  "request_id": "req_9c4b3dc2e5f6",
  "completed": 3,
  "page": {
    "url": "https://example.com/results?q=search+query",
    "title": "Search Results",
    "stable": true,
    "markdown": {"content": "# Search Results\n\n## 1. First result..."},
    "interactive_elements": [
      {"ref": "e1", "tag": "input", "role": "search", "label": "Search", "value": "search query", "in": "form", "form": "f1"},
      {"ref": "e2", "tag": "a", "role": "link", "label": "First result", "in": "main", "near": "Search Results"},
      {"ref": "e3", "tag": "a", "role": "link", "label": "Second result", "in": "main", "near": "Search Results"}
    ],
    "forms": [
      {"ref": "f1", "id": "search", "action": "/search", "method": "GET", "fields": ["e1"]}
    ],
    "changes": {
      "content_changed": true,
      "elements_added": [{"ref": "e2"}, {"ref": "e3"}],
      "elements_removed": []
    },
    "scroll": {"y": 0, "height": 3000, "viewport": 720, "percent": 24}
  },
  "media": [{"type": "screenshot", "format": "png", "data": "<base64>"}],
  "extraction": null,
  "blockers_dismissed": [],
  "error": null
}

DELETE /v1/sessions/:id

Destroy a session and release browser resources. Runtime is recorded for billing.

curl -X DELETE https://api.browserbeam.com/v1/sessions/ses_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

client.sessions.destroy(session.session_id)  # 204 No Content

await client.sessions.destroy(session.sessionId);  // 204 No Content

client.sessions.destroy(session.session_id)  # 204 No Content

# Empty response — session destroyed

GET /v1/sessions

List sessions for the authenticated API key. Supports cursor-based pagination and status filtering.

curl "https://api.browserbeam.com/v1/sessions?status=active&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

result = client.sessions.list(status="active", limit=25)

const result = await client.sessions.list({ status: "active", limit: 25 });

result = client.sessions.list(status: "active", limit: 25)

{
  "sessions": [
    {
      "session_id": "ses_abc123",
      "status": "active",
      "started_at": "2026-03-18T13:55:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

goto

Navigate to a URL. Waits for page load and stability checks.

{"goto": {"url": "https://example.com"}}

{"goto": {"url": "https://example.com", "wait_for": "#main-content", "wait_timeout": 15000}}

{"goto": {"url": "https://example.com", "wait_until": "window.__APP_READY === true", "wait_timeout": 10000}}

On failure (DNS error, timeout, SSL), returns error code navigation_failed.

observe

Force a page observation. Auto-observe runs at the end of every call, so explicit observe is only needed to change format or scope mid-pipeline.

{"observe": {}}

{"observe": {"format": "html"}}

{"observe": {"scope": "#content", "include_links": true}}

{"observe": {"mode": "full", "max_text_length": 20000}}

{"observe": {"include_page_map": true}}

click

Click an element. Exactly one targeting param required (see Element Targeting).

{"click": {"ref": "e3"}}

{"click": {"text": "Submit"}}

{"click": {"label": "Sign in"}}

fill

Clear and replace the value of an input. For character-by-character typing, use type instead.

{"fill": {"ref": "e1", "value": "hello world"}}

{"fill": {"label": "Email", "value": "user@example.com"}}

type

Type character-by-character with a delay. Use for autocomplete and search-as-you-type inputs.

{"type": {"label": "Search", "value": "browserbeam api", "delay": 100}}

select

Select an option from a <select> dropdown.

{"select": {"label": "Country", "value": "US"}}

{"select": {"ref": "e4", "value": "option_value"}}

check

Check or uncheck a checkbox/radio button.

{"check": {"label": "Remember me"}}

{"check": {"label": "Terms", "checked": false}}

scroll

Scroll the page or scroll an element into view.

{"scroll": {"to": "bottom"}}

{"scroll": {"direction": "down", "amount": 500, "times": 3}}

{"scroll": {"ref": "e6"}}

scroll_collect

Scroll through the entire page, wait for lazy-loaded content at each position, and return a unified observation. Ideal for infinite scroll and long pages.

{"scroll_collect": {}}

{"scroll_collect": {"max_scrolls": 30, "max_text_length": 50000}}

screenshot

Capture a screenshot. Base64 data appears in the media array with type: "screenshot".

{"screenshot": {}}

{"screenshot": {"full_page": true, "format": "jpeg", "quality": 80}}

{"screenshot": {"selector": "#chart"}}

wait

Wait for a condition. Exactly one of ms, selector, text, or until is required.

{"wait": {"ms": 2000}}

{"wait": {"selector": "#results", "timeout": 10000}}

{"wait": {"text": "Loading complete", "timeout": 5000}}

// Wait for a JS expression to become truthy
{"wait": {"until": "document.querySelectorAll('.item').length >= 10", "timeout": 15000}}

extract

Structured data extraction. Keys are your field names, values are CSS/XPath selectors. Results appear in the extraction object of the response.

Selector syntax

// Pattern: "selector >> function"
// Functions: text, href (any attr), json, or omit for raw HTML

"title":      "h1 >> text"
"link":       "a.main >> href"
"image":      "img.hero >> src"
"meta":       "meta[name=description] >> content"
"html_block": "div.content"

Arrays

// Wrap in [ ] to collect all matches
"all_links": ["a >> href"]
"headings":  ["h2 >> text"]

Repeating structures

// Use [{_parent}] for repeating items like product cards
"products": [
  {
    "_parent": ".product-card",
    "name":    "h2 >> text",
    "price":   ".price >> text",
    "url":     "a >> href"
  }
]

Tables

// Tables are auto-parsed into arrays using headers as keys
"people": "table.contacts"
// → [{"Name": "Alice", "Email": "alice@example.com"}, ...]

JavaScript expressions

// Use js >> prefix to run JavaScript in the browser
"count": "js >> document.querySelectorAll('.item').length"
"title": "js >> document.querySelector('h1').textContent.trim()"

AI-powered selectors

Use the ai >> prefix to describe an element in plain English. The engine resolves it to a real CSS selector via AI, caches it per user and domain, and reuses it on subsequent calls at zero additional cost.

// Mix AI selectors with regular CSS selectors in the same schema
"products": [
  {
    "_parent": "article.product_pod",
    "name":  "ai >> the product title",
    "price": "ai >> the price including currency symbol",
    "stock": ".instock >> text"
  }
]

AI selectors consume AI tokens (billed as credits). Once cached, subsequent calls reuse the resolved CSS selector for free. Use refresh_selectors: true inside the extract step to force re-resolution if a site's structure changes.

Full example

{
  "url": "https://example.com/products",
  "steps": [
    {
      "extract": {
        "page_title": "h1 >> text",
        "description": "meta[name=description] >> content",
        "nav_links": ["nav a >> text"],
        "articles": [
          {
            "_parent": ".article-card",
            "title": "h2 >> text",
            "url": "a >> href",
            "author": ".byline >> text"
          }
        ],
        "stats_table": "table.statistics"
      }
    },
    {"close": {}}
  ]
}

{
  "session_id": "ses_xyz789",
  "completed": 2,
  "page": { "..." : "..." },
  "extraction": {
    "page_title": "Our Products",
    "description": "Browse our full catalog",
    "nav_links": ["Home", "Products", "About", "Contact"],
    "articles": [
      {"title": "Widget Pro", "url": "https://example.com/widget-pro", "author": "Jane"},
      {"title": "Gadget X", "url": "https://example.com/gadget-x", "author": "John"}
    ],
    "stats_table": [
      {"Product": "Widget Pro", "Sales": "1,234", "Rating": "4.8"},
      {"Product": "Gadget X", "Sales": "567", "Rating": "4.5"}
    ]
  },
  "media": [],
  "error": null
}

fill_form

Fill multiple form fields by label and optionally submit. Auto-detects field types (text, select, checkbox).

{
  "fill_form": {
    "fields": {
      "Email": "user@example.com",
      "Password": "secret",
      "Country": "US",
      "Remember me": true
    },
    "submit": true
  }
}

upload

Upload files to a file input. Downloads from provided URLs and attaches them.

{"upload": {"ref": "e5", "files": ["https://example.com/doc.pdf"]}}

{"upload": {"label": "Resume", "files": ["https://example.com/resume.pdf"]}}

pdf

Generate a PDF of the current page. Base64 data in the media array with type: "pdf".

{"pdf": {}}

{"pdf": {"format": "A4", "landscape": true, "margin": {"top": "1cm", "bottom": "1cm"}}}

execute_js

Run custom JavaScript in the browser context. The return value is placed in the extraction object under the specified key.

// Get the page title
{"execute_js": {"code": "return document.title"}}

// Count elements on the page
{"execute_js": {"code": "return document.querySelectorAll('.product').length", "result_key": "product_count"}}

// Extract computed data
{"execute_js": {"code": "return { url: location.href, cookies: document.cookie, scrollY: window.scrollY }"}}

The code runs inside a new Function() wrapper, so use return to send values back. Execution is sandboxed within the page context — no access to Node.js APIs.

close

Destroy the session at the end of step execution. Must be the last step. Useful for fire-and-forget workflows.

{"close": {}}

Element Targeting

Steps that interact with elements (click, fill, type, select, check, scroll, upload) accept exactly one targeting param:

Label matching checks (in order): aria-label, placeholder, associated <label>, name attribute, nearby text.

Response Format

Create and act calls return the same response structure.

Errors

All errors follow a consistent JSON format. On step failure, the response includes both the error and the current page state so you can decide what to do next:

{
  "completed": 1,
  "page": {
    "url": "https://example.com",
    "title": "Example Domain",
    "interactive_elements": ["..."]
  },
  "error": {
    "step": 1,
    "action": "click",
    "code": "element_not_found",
    "message": "No visible element found matching text \"Submit\"",
    "context": {}
  }
}

HTTP errors

Step error codes

Recovery patterns

Retry example

import time, requests

def call_with_retry(url, headers, json, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(url, headers=headers, json=json)
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        if resp.status_code == 503:
            time.sleep(2 ** attempt)
            continue
        return resp
    raise Exception(f"Failed after {max_retries} retries")

Rate Limits & Quotas

Usage is metered in credits. Runtime, proxy bandwidth, AI selector resolutions, and CAPTCHA solves all consume credits from a single pool. Limits depend on your plan.

Response headers

Every API response includes rate limit headers so you can track your quota:

Plans

See Billing & Credits for credit rates and how each service is metered.

Workflows

Common patterns showing how to combine sessions and steps.

Explore then act — 2 calls

Get page state first, then use element refs to interact.

{"url": "https://example.com"}

{
  "steps": [
    {"fill": {"ref": "e1", "value": "search query"}},
    {"click": {"ref": "e3"}}
  ]
}

Login + screenshot — 1 call

Fill a login form, take a screenshot, destroy the session — all at once.

curl -X POST https://api.browserbeam.com/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/login",
    "steps": [
      {"fill_form": {"fields": {"Email": "user@test.com", "Password": "pass"}, "submit": true}},
      {"wait": {"ms": 2000}},
      {"screenshot": {"full_page": true}},
      {"close": {}}
    ]
  }'

from browserbeam import Browserbeam

client = Browserbeam(api_key="YOUR_API_KEY")
with client.sessions.create(url="https://example.com/login") as session:
    session.fill_form({"Email": "user@test.com", "Password": "pass"}, submit=True)
    session.wait(ms=2000)
    session.screenshot(full_page=True)

import Browserbeam from "@browserbeam/sdk";

const client = new Browserbeam({ apiKey: "YOUR_API_KEY" });
const session = await client.sessions.create({ url: "https://example.com/login" });
await session.fillForm({ fields: { Email: "user@test.com", Password: "pass" }, submit: true });
await session.wait({ ms: 2000 });
await session.screenshot({ full_page: true });
await session.close();

require "browserbeam"

client = Browserbeam::Client.new(api_key: "YOUR_API_KEY")
client.sessions.create(url: "https://example.com/login") do |session|
  session.fill_form({"Email" => "user@test.com", "Password" => "pass"}, submit: true)
  session.wait(ms: 2000)
  session.screenshot(full_page: true)
end

{
  "url": "https://example.com/login",
  "steps": [
    {"fill_form": {"fields": {"Email": "user@test.com", "Password": "pass"}, "submit": true}},
    {"wait": {"ms": 2000}},
    {"screenshot": {"full_page": true}},
    {"close": {}}
  ]
}

Full-page scrape — 1 call

Scroll through the entire page, collecting all lazy-loaded content.

{
  "url": "https://example.com/long-article",
  "steps": [{"scroll_collect": {"max_text_length": 50000}}]
}

Structured extraction — 1 call

Extract structured data and close the session in one request.

{
  "url": "https://example.com/products",
  "steps": [
    {"extract": {"products": [{"_parent": ".product", "name": "h2 >> text", "price": ".price >> text", "url": "a >> href"}]}},
    {"close": {}}
  ]
}

PDF generation — 1 call

Generate a PDF and close the session.

{
  "url": "https://example.com/report",
  "steps": [{"pdf": {"format": "A4", "landscape": true}}, {"close": {}}]
}

Search + extract — 2 calls

Navigate, perform a search, then extract results.

{
  "url": "https://example.com",
  "steps": [
    {"fill": {"label": "Search", "value": "browser automation"}},
    {"click": {"text": "Search"}}
  ]
}

{
  "steps": [
    {"extract": {"results": [{"_parent": ".result", "title": "h3 >> text", "url": "a >> href"}]}},
    {"close": {}}
  ]
}

Building an LLM agent loop — N calls

The most common pattern for AI agents: create a session, observe, decide, act, repeat until done.

from browserbeam import Browserbeam

client = Browserbeam(api_key="YOUR_API_KEY")

# 1. Create session and navigate
session = client.sessions.create(url="https://example.com")

# 2. Agent loop: observe → decide → act
while True:
    page = session.page
    elements = page.interactive_elements

    # 3. Send page state to your LLM to decide next action
    next_steps = llm_decide(page.markdown.content, elements)

    if next_steps is None:
        break  # Goal reached

    # 4. Execute the steps
    session.act(next_steps)

    if session.error:
        print(f"Step failed: {session.error.message}")
        break

# 5. Clean up
client.sessions.destroy(session.session_id)

import Browserbeam from "@browserbeam/sdk";

const client = new Browserbeam({ apiKey: "YOUR_API_KEY" });

// 1. Create session and navigate
const session = await client.sessions.create({ url: "https://example.com" });

// 2. Agent loop: observe → decide → act
while (true) {
  const { page } = session;

  // 3. Send page state to your LLM to decide next action
  const nextSteps = await llmDecide(page.markdown.content, page.interactive_elements);

  if (!nextSteps) break; // Goal reached

  // 4. Execute the steps
  await session.act(nextSteps);

  if (session.error) {
    console.error(`Step failed: ${session.error.message}`);
    break;
  }
}

// 5. Clean up
await client.sessions.destroy(session.sessionId);

require "browserbeam"

client = Browserbeam::Client.new(api_key: "YOUR_API_KEY")

# 1. Create session and navigate
session = client.sessions.create(url: "https://example.com")

# 2. Agent loop: observe → decide → act
loop do
  page = session.page
  elements = page.interactive_elements

  # 3. Send page state to your LLM to decide next action
  next_steps = llm_decide(page.markdown.content, elements)

  break unless next_steps  # Goal reached

  # 4. Execute the steps
  session.act(next_steps)

  if session.error
    puts "Step failed: #{session.error.message}"
    break
  end
end

# 5. Clean up
client.sessions.destroy(session.session_id)

The key insight: every response includes fresh page state via auto-observe, so your LLM always has up-to-date content and element refs to decide its next action.