Skip to main content

​
My API key has credits, but a request fails

Read GET /api/v2/billing/account with the same key. It also works for V4 users. Confirm the projectId, balance, and concurrentSessionLimit against the project selected in the dashboard. Keys in different projects do not share credits. A pay-as-you-go account can legitimately have planInfo: null. Read the complete error response before changing billing settings: See billing, concurrency, and workspaces for the relevant limits and remedies.

​
Restricted API keys

When you create a key in Settings → API keys, turn off Full access to pick a permission per resource: Read lists and gets, Write also creates and deletes. A request outside the key’s permissions returns 403 with the missing scope. Scopes have the form <version>:<resource>:<action>, with actions read, create, and delete, and * as a wildcard. Full-access keys hold *:*:*. V4 resources are runs, sessions, workspaces, files, browsers, profiles, proxy, integrations, licenses, extensions, and imessage. The wallet endpoints (GET /agentcard/wallets, GET /stripe-link) need Read on runs. Scopes cannot be changed after a key is created, and a restricted key does not gain resources added later unless it holds a wildcard such as v4:*:*. Create a new key with the permissions you need.

​
Why am I charged when I bring my own key or proxy?

BYOK means your model provider bills its tokens. Browser Use still charges orchestration plus browser and network usage. A custom proxy has its own provider charges and does not remove Browser Use browser/network charges. A Claude or ChatGPT consumer subscription is not a provider API key. See the billing breakdown.

​
The dashboard works, but the same integration does not

Check the API key’s project, selected model, profile, proxy settings, and API version. A connected integration in the dashboard does not automatically grant every API run access to it. Pass the documented run-level bindings or grants. For example, see 1Password and Secrets. A site can also challenge a fresh browser even if it accepts an existing logged-in browser. Reuse an appropriate profile, and compare the actual proxy configuration before changing the agent prompt.

​
A checkout secret is refused

The payment field may be inside a provider’s iframe. For domain_not_allowed, add that intended provider’s hostname to the secret binding’s allowedDomains and resend the binding in a follow-up run. For target_not_editable, check field focus and readiness instead. See checkout and payment frames.

​
The browser is idle, but usage continues

A completed V4 agent run keeps its browser open about 2 minutes, or for the run’s keepAlive seconds, so a follow-up can reuse it. That time is billed but takes no concurrency slot. Closing your SDK client or disconnecting CDP does not stop the managed browser. Stop an unneeded browser with PATCH /api/v4/browsers/{id} and {"action":"stop"}. See browser lifetime. If a local wait times out, the server may still be running. Fetch the existing run’s status before creating a replacement, especially if it might already have submitted a form or performed another external action.

​
I cannot find a file or recording

Wait for the run to finish before listing generated files, and use its V4 workspace ID. Request a fresh download URL if an old one expired. A session’s conversation, workspace files, and browser profile are different resources. See Workspaces and files. Recordings are off by default for API browsers. Enable recording when creating the browser, stop it when finished, and allow time for processing. A live preview is not a stored video. See Live preview and recording.

​
Does a new browser guarantee a new IP or a CAPTCHA bypass?

No. Selecting a proxy country chooses a location; it does not promise a particular city or a unique IP on every launch. Websites can still block requests or require human verification. Let the automatic solver work before clicking or refreshing a challenge. See proxies and CAPTCHA handling.

​
What should I send support?

If you hit an issue you cannot explain, email contact@browser-use.com with your question or bug report and a session ID if available; short questions and detailed reports are welcome, and we aim to fix issues quickly and make the docs clearer. The details below help us investigate, but you do not need all of them to ask. Include the API version and endpoint, run/session/browser/workspace IDs that apply, the project ID, timestamp with time zone, SDK version, and the complete redacted error response. State what you expected and what actually happened. For billing, include the payment reference and selected project; for a file problem, include the filename, size, and the operation that failed. Do not send API keys, passwords, card details, custom-proxy credentials, session cookies, or active CDP/live-view URLs. A screenshot alone often omits the identifier needed to trace a request.