Account Tools
The Browserless MCP server exposes five read-only tools that report on the account behind your API token: plan and billing, unit consumption, Browserless-side request logs, sessions and replays, and saved authentication profiles. Use them to let your AI assistant answer questions like "what plan am I on", "why did my run fail", or "which login profiles already exist" without leaving the conversation.
All five are stateless: one call in, one result out. None of them changes account state, stops a session, or returns API token values.
- Set up the Browserless MCP Server in your MCP client (Claude Desktop, Cursor, VS Code, Windsurf, Claude Code, etc.)
browserless_account
Reads the account behind the current API token: plan, unit balance, billing period, payment status, and the names of the account's API keys. Token values are never returned; create or rotate keys in the dashboard.
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | Yes | Which part of the account to read: billing returns the plan, unit balance, and billing period; keys lists the account API keys by name and id |
Key ids returned by action: "keys" can be passed as apiKeyId to browserless_logs or apiKeyIds to browserless_usage to scope those reads to one key.
Example prompts:
What plan am I on, and how many units are left this period?
List my API keys and tell me which ones are revoked.
browserless_usage
Reads request and unit consumption for the account: successes, errors, timeouts, queueing, rejections, peak concurrency, CAPTCHAs solved, proxy usage, and billed units for the current period. For per-request detail on failures, use browserless_logs instead.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
timeframe | string | No | "day" | Window the request counts cover: hour, day, or week |
apiKeyIds | string[] | No | — | Restrict the numbers to specific API keys, by id (max 50). Omit for the whole account. Get ids from browserless_account with action: "keys" |
Example prompts:
How much have I used this week?
Why is my bill high? Break down usage by my production API key.
browserless_logs
Reads Browserless's own record of the account's recent requests: what was attempted, whether it failed, why it stopped, how long it took, and what it cost. This is the tool for diagnosing a run that failed on the Browserless side rather than in your own code. How far back you can query depends on the account plan; the server reports the limit if a range is refused.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
startTime | string | No | plan window | Inclusive RFC 3339 start time. Omit to let the plan decide how far back to look |
endTime | string | No | now | Exclusive RFC 3339 end time |
limit | number | No | 50 | Maximum entries to return (1-100) |
requestId | string | No | — | Return only entries for one request id |
url | string | No | — | Filter by the target URL of the request |
eventNames | string[] | No | — | Filter by lifecycle event name, e.g. request.failed, bql.*.failed (max 20) |
outcome | string | No | — | Filter by request outcome, e.g. failed or succeeded |
apiKeyId | string | No | — | Restrict to one API key, by id |
endpoint | string | No | — | Filter by endpoint, e.g. /chromium/bql or /screenshot |
category | string | No | — | Filter by failure category, e.g. browserless_refused, browserless_killed, target_error |
reason | string | No | — | Filter by the specific failure reason within a category |
levels | string[] | No | all | Severity levels to include: TRACE, DEBUG, INFO, WARN, ERROR, FATAL |
order | string | No | "desc" | Timestamp order: asc or desc (newest first) |
cursor | string | No | — | Opaque cursor returned as nextCursor by the previous page |
Example prompts:
Show me every request that failed in the last hour and why.
Pull the logs for request id abc123 so we can see where it stopped.
browserless_sessions
Inspects the sessions on the account: browsers running right now, persistent sessions saved on dedicated workers, recorded session replays, and 1Password credential integrations. Read-only; it never stops a session. The replay action downloads one recording and returns a self-contained playable rrweb page that needs no network access to render.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
action | string | Yes | — | Which session data to read: active (browsers running right now), persistent (saved sessions on dedicated workers, running or not), replays (list recorded session replays), replay (download one replay as a playable page; needs sessionId), integrations (1Password credential integrations) |
sessionId | string | No | — | Which replay to download, for action: "replay". Get ids from action: "replays" |
limit | number | No | — | Maximum rows to return (max 50). Applies to every action |
skip | number | No | 0 | Rows to skip, for paging through active or integrations |
page | number | No | 1 | Page number for replays (1-based) |
search | string | No | — | Filter replays by website or session id |
Example prompts:
What browser sessions are running on my account right now?
Find the replay of my last checkout run and play it back.
browserless_profiles
Lists the authentication profiles saved for the current token. A profile is a saved logged-in browser state (cookies plus storage) that other tools can replay by passing its name as profile. Call it before a task that needs the browser to start signed in, to discover which profiles exist and pick one by name. Returns each profile's name, cookie and origin counts, and last-used time.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | number | No | 100 | Maximum number of profiles to return (max 1000) |
offset | number | No | 0 | Number of profiles to skip, for pagination |
Profiles are created by running an authenticated session with createProfile; the Browser Agent walks through this when a task needs a login.
Example prompt:
Which login profiles do I have saved, and when was each last used?
FAQ & Troubleshooting
Why does browserless_usage show zero requests but a non-zero unit count?
The per-request counters and the billed-unit ledger come from different sources. On shared cloud-unit plans the request counters can be empty while the unit ledger still records consumption, so the billed-units section is the number that answers "how much have I used". Scope by apiKeyIds if you need to attribute usage to a specific key.
Why was my browserless_logs time range rejected?
The log window you can query is plan-dependent. If your startTime reaches further back than the plan allows, the server refuses the range and reports the limit in the error. Retry with a startTime inside that window, or omit it to get the widest range your plan supports.
Can these tools change my account, or leak my API tokens?
No. All five tools are read-only: they never modify plans or keys, never stop a session, and never return API token values. browserless_account returns key names and ids only; create or rotate the actual tokens in the account dashboard.