The Browser Use connector lets your AI agent act in each user's Browser Use account. Each user connects their own Browser Use API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 19 tools.
- Tools
- 19
- What they doRead · write · destructive
- 11 · 7 · 111 read7 write1 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Browser Use connection
In AgentKit > Connections, create a Browser Use connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'browseruse'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Browser Use:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'browseruse_list_browsers',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "browseruse"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Browser Use:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="browseruse_list_browsers",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Browser Use credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolbrowseruse_get_browserGet a Browser Use cloud browser and its current state.Read-onlyGet Browser
Get a Browser Use cloud browser and its current state. Returns id, status (active or stopped), cdpUrl, liveUrl, timeoutAt, startedAt, finishedAt, browserCost, proxyCost, proxyUsedMb, agentSessionId and, after it stops, recordingUrl when recording was on. Use this to check whether a browser is still running, get its connection URLs or fetch its recording. Use browseruse_list_browsers to find browser IDs.
Inputs
browser_idstringrequired- ID of the cloud browser (a UUID), returned as id by browseruse_create_browser or listed by browseruse_list_browsers. Example: c4e9a1f7-5b2d-4c8e-9a3f-1d6b0e7c2a95
browseruse_get_runGet the full details and result of a Browser Use agent run.Read-onlyGet Run
Get the full details and result of a Browser Use agent run. Returns the task, status, result (the agent's final answer as text), output (structured JSON when an output schema was set), error, model, token counts, totalCostUsd, sessionId and workspaceId. Use this once browseruse_get_run_status reports completed, failed or cancelled. Use browseruse_get_run_events for the step-by-step trace and browseruse_list_workspace_files for files the agent saved.
Inputs
run_idstringrequired- ID of the agent run (a UUID), returned as id by browseruse_create_run or listed by browseruse_list_runs. Example: 6f1c2b9e-3d4a-4f8b-9c2e-7a5d1e0b8c34
browseruse_get_run_eventsRead the step-by-step event log of a Browser Use agent run, such as browser start, agent actions, tool output and the final answer.Read-onlyGet Run Events
Read the step-by-step event log of a Browser Use agent run, such as browser start, agent actions, tool output and the final answer. Returns events (id, ts, type and data), plus nextAfter and hasMore for paging. Use this to follow progress or debug a run. Pass the nextAfter value as after to get only newer events. Use browseruse_get_run for the final result alone.
Inputs
run_idstringrequired- ID of the agent run (a UUID), returned as id by browseruse_create_run or listed by browseruse_list_runs. Example: 6f1c2b9e-3d4a-4f8b-9c2e-7a5d1e0b8c34
afterinteger- Return only events with an id greater than this. Pass the nextAfter value from the previous response; omit or 0 to start from the beginning. Example: 42
include_outputboolean- Set false to leave out tool output in each event, which keeps the response small. Default true.
limitinteger- Maximum number of events to return. The API default is 200. Example: 100
browseruse_get_run_statusCheck the status of a Browser Use agent run.Read-onlyGet Run Status
Check the status of a Browser Use agent run. Returns only status: queued, dispatching, running, completed, failed or cancelled. Use this to poll a run started by browseruse_create_run; it is cheap and fast. Use browseruse_get_run once the status is final to read the answer, cost and error.
Inputs
run_idstringrequired- ID of the agent run (a UUID), returned as id by browseruse_create_run or listed by browseruse_list_runs. Example: 6f1c2b9e-3d4a-4f8b-9c2e-7a5d1e0b8c34
browseruse_get_sessionGet a Browser Use agent session and the state of its latest run.Read-onlyGet Session
Get a Browser Use agent session and the state of its latest run. Returns sessionId, title, task, status and latestRunId of the latest run, workspaceId and timestamps. Use this to check whether a session is busy or idle before sending a follow-up. Use browseruse_get_run with latestRunId for the result, and browseruse_get_session_cost for spending.
Inputs
session_idstringrequired- ID of the agent session (a UUID). Every run belongs to a session; it is returned as sessionId by browseruse_create_run and browseruse_get_run, and listed by browseruse_list_sessions. Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
browseruse_get_session_costGet everything a Browser Use agent session has cost so far, split by source.Read-onlyGet Session Cost
Get everything a Browser Use agent session has cost so far, split by source. Returns numRuns, llmCostUsd, searchCostUsd, browserCostUsd, proxyCostUsd, proxyUsedMb and totalCostUsd as decimal strings. Use this for the full cost of a session including browser time and proxy traffic. A run's totalCostUsd from browseruse_get_run covers model and search charges only. Costs can still rise for about 90 seconds after a run finishes and while its browser stays open.
Inputs
session_idstringrequired- ID of the agent session (a UUID). Every run belongs to a session; it is returned as sessionId by browseruse_create_run and browseruse_get_run, and listed by browseruse_list_sessions. Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
browseruse_list_browser_downloadsList files a Browser Use cloud browser downloaded during its session.Read-onlyList Browser Downloads
List files a Browser Use cloud browser downloaded during its session. Returns files with path, size and lastModified, plus a download url for each when include_urls is true (valid for 15 minutes), and nextCursor and hasMore for paging. Use this to collect files saved by a browser you drove over CDP. Use browseruse_list_workspace_files for files an agent run saved.
Inputs
browser_idstringrequired- ID of the cloud browser (a UUID), returned as id by browseruse_create_browser or listed by browseruse_list_browsers. Example: c4e9a1f7-5b2d-4c8e-9a3f-1d6b0e7c2a95
cursorstring- Pagination cursor. Pass the nextCursor value from the previous response to get the next page of downloads; omit for the first page.
include_urlsboolean- Set true to include a presigned download url for each file, valid for 15 minutes. Default false.
limitinteger- Maximum number of files to return, from 1 to 100. The API default is 50. Example: 50
browseruse_list_browsersList Browser Use cloud browsers in the project, optionally only active or stopped ones, those of one agent session, or those with given labels.Read-onlyList Browsers
List Browser Use cloud browsers in the project, optionally only active or stopped ones, those of one agent session, or those with given labels. Returns browsers with id, status, liveUrl, cdpUrl, timeoutAt, startedAt, finishedAt, costs and labels, plus paging totals. Use this to find running browsers to stop or to review usage. Use browseruse_get_browser for one browser's recording URL.
Inputs
agent_session_idstring- Only list browsers started by this agent session (a UUID). Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
metadataarray- Only list browsers that carry every one of these labels. Use key to match any value or key=value to match exactly. Example: ["customer=acme"]
page_numberinteger- Page to return, starting at 1. The API default is 1. Example: 2
page_sizeinteger- Browsers per page, from 1 to 100. The API default is 10. Example: 20
statusstring- Only list browsers in this state: active (still running) or stopped.one of
activestopped
browseruse_list_runsList Browser Use agent runs in the project, newest first, optionally for one session.Read-onlyList Runs
List Browser Use agent runs in the project, newest first, optionally for one session. Returns runs with id, task, title, status, result, output, error, model, totalCostUsd, sessionId and timestamps, plus nextCursor and hasMore for paging. Use this to find a run or see every turn of a session. Use browseruse_list_sessions for one row per conversation.
Inputs
cursorstring- Pagination cursor. Pass the nextCursor value from the previous response to get the next page of runs; omit for the first page.
limitinteger- Maximum number of runs to return. The API default is 50. Example: 20
session_idstring- Only list runs that belong to this session (a UUID). Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
browseruse_list_sessionsList Browser Use agent sessions (conversations) in the project, most recent first.Read-onlyList Sessions
List Browser Use agent sessions (conversations) in the project, most recent first. Returns sessions with sessionId, title, task, status and latestRunId of their latest run, workspaceId and timestamps, plus nextCursor and hasMore for paging. Use this to find a conversation to continue or inspect. Use browseruse_list_runs to see each run inside a session.
Inputs
cursorstring- Pagination cursor. Pass the nextCursor value from the previous response to get the next page of sessions; omit for the first page.
limitinteger- Maximum number of sessions to return, from 1 to 100. The API default is 20. Example: 20
browseruse_list_workspace_filesList files that Browser Use agents saved in a workspace, such as exported CSVs, screenshots or reports.Read-onlyList Workspace Files
List files that Browser Use agents saved in a workspace, such as exported CSVs, screenshots or reports. Returns files with path, size and lastModified, plus a short-lived download url for each when include_urls is true, and nextCursor and hasMore for paging. Use this after a run finishes to collect its file output. Get the workspace ID from the run's workspaceId in browseruse_create_run or browseruse_get_run. Use browseruse_list_browser_downloads for files a standalone browser downloaded.
Inputs
workspace_idstringrequired- ID of the workspace (a UUID), returned as workspaceId by browseruse_create_run and browseruse_get_run. Example: 8d3a6f2e-1b4c-4a9d-b7e5-0c2f9a1d6e48
cursorstring- Pagination cursor. Pass the nextCursor value from the previous response to get the next page of files; omit for the first page.
include_urlsboolean- Set true to include a presigned download url for each file. The links expire after about 60 seconds, so download right away. Default false.
limitinteger- Maximum number of files to return, from 1 to 100. The API default is 50. Example: 50
prefixstring- Only list files whose path starts with this text, for example a folder name. Example: reports/
browseruse_cancel_runCancel an in-progress Browser Use agent run so it stops working and stops incurring model charges.WriteCancel Run
Cancel an in-progress Browser Use agent run so it stops working and stops incurring model charges. Returns the run's details with its status. A run that already finished is returned unchanged. Use this to stop one run. Use browseruse_stop_browser to also shut down a kept-alive browser, or browseruse_delete_session to cancel and hide the whole session.
- Idempotent
Inputs
run_idstringrequired- ID of the agent run (a UUID), returned as id by browseruse_create_run or listed by browseruse_list_runs. Example: 6f1c2b9e-3d4a-4f8b-9c2e-7a5d1e0b8c34
browseruse_create_browserStart a Browser Use stealth cloud browser that your own code controls over the Chrome DevTools Protocol, with no AI agent attached.WriteCreate Browser
Start a Browser Use stealth cloud browser that your own code controls over the Chrome DevTools Protocol, with no AI agent attached. Returns the browser id, status, cdpUrl (connect Playwright, Puppeteer or browser-use to it), liveUrl (watch it live) and timeoutAt. Use this when you drive the browser yourself. Use browseruse_create_run to have a Browser Use agent do the task instead. The browser is billed by the minute until it times out or browseruse_stop_browser stops it, so stop it when you are done.
Inputs
enable_recordingboolean- Set true to record the session to a video. The recording URL appears on browseruse_get_browser after the browser stops. Default false.
metadataobject- Up to 10 string labels as key-value pairs, used to filter browseruse_list_browsers. Example: {"customer": "acme", "job": "price-check"}
profile_idstring- Browser profile (a UUID) to load, with its saved cookies and logins. Example: a9d2c5e8-7f1b-4e3a-8c6d-2b0f9e4a1c57
proxy_country_codestring- Two-letter lowercase ISO country code of the residential proxy the browser uses. Defaults to us. Example: gb
screen_heightinteger- Screen height in pixels, from 320 to 3456. Example: 1080
screen_widthinteger- Screen width in pixels, from 320 to 6144. Example: 1920
solve_captchasboolean- Set false to handle CAPTCHAs yourself. By default the browser detects and solves supported CAPTCHAs on its own.
timeoutinteger- Minutes before the browser shuts down on its own, from 1 to 240. The API default is 60. Unused time is refunded when you stop it early. Example: 30
browseruse_create_runStart a Browser Use cloud agent run: the agent opens a stealth cloud browser and works on a task you describe in plain language.WriteCreate Run
Start a Browser Use cloud agent run: the agent opens a stealth cloud browser and works on a task you describe in plain language. Returns the run id, sessionId, workspaceId and status (usually queued). The run continues in the background. Use this to start new work, or pass session_id to continue an idle session with the same browser and history. Use browseruse_send_session_message to add a message to a session that may still be busy. Poll browseruse_get_run_status until status is completed, failed or cancelled, then read the answer with browseruse_get_run.
Inputs
taskstringrequired- What the agent should do, in plain language. Include the website, the steps and what to report back. Example: Go to news.ycombinator.com and return the titles and URLs of the top 5 stories.
agentmailboolean- Set true to give the agent a temporary email inbox it can send, receive and read mail with (for sign-ups or email codes). Default false.
keep_aliveinteger- Seconds (120 to 14400) the session's browser stays open after the run ends so a follow-up can reuse the same page. Default 120. Kept time is billed as browser time. Example: 600
max_cost_usdnumber- Budget in USD for model and web-search charges across the session. New sessions default to 25. On a follow-up, omit to keep the current budget; a value replaces it. Browser time and proxy traffic are billed separately. Example: 5
modelstring- Model the agent runs on. Omit to use Browser Use's default (gpt-6-luna with high reasoning). Values change as Browser Use adds models; current examples include gpt-6-luna, gpt-6-sol, gpt-6-astra, claude-sonnet-5, claude-opus-5, gemini-3.1-pro, gemini-3-flash and the early-access presets bu-fast and bu-ultrafast. An unsupported value is rejected with a 422 error.
model_paramsobject- Provider-native parameters for the chosen model, forwarded unchanged, such as reasoning effort. Examples: {"reasoning": {"effort": "high"}} for OpenAI models, {"thinking": {"type": "adaptive"}} for Anthropic models, {"thinkingConfig": {"thinkingLevel": "high"}} for Google models. Pass {} to turn off the model's default parameters. Not accepted by bu-fast and bu-ultrafast.
output_schemaobject- JSON Schema for a structured answer. When set, the agent returns JSON matching it in the run's output field. Pass a JSON object (or the same object as a JSON string). Example: {"type": "object", "properties": {"stories": {"type": "array", "items": {"type": "object", "properties": {"title": {"type": "string"}, "url": {"type": "string"}}}}}}
profile_idstring- Browser profile (a UUID) to load, with its saved cookies and logins. Create profiles in the Browser Use dashboard. Example: a9d2c5e8-7f1b-4e3a-8c6d-2b0f9e4a1c57
proxy_country_codestring- Two-letter lowercase ISO country code of the residential proxy the browser uses. Defaults to us. Example: de
recordboolean- Set true to record the browser to an MP4 video. The recording URL appears on browseruse_get_browser after the browser stops. Default false.
session_idstring- Continue this existing session (a UUID from a previous run's sessionId) so the agent keeps its conversation history and, while it is still open, the same browser. Omit to start a new session. Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
workspace_idstring- Files workspace for the run (a UUID). Omit on a new session to create one; omit on a follow-up to reuse the session's workspace. Example: 8d3a6f2e-1b4c-4a9d-b7e5-0c2f9a1d6e48
browseruse_send_session_messageSend a follow-up message to a Browser Use agent session.WriteSend Session Message
Send a follow-up message to a Browser Use agent session. If the session is busy the message waits in its queue and runs as the next turn; if it is idle it starts a new run right away. Returns the queued message with id, status (pending, dispatching, consumed, cancelled, superseded or failed), mode and runId once a run picks it up. Use this to steer or continue a conversation, or set interrupt to cancel the current run and act on this message now. Use browseruse_create_run with session_id to change the model, budget or browser settings for the follow-up. Get the session ID from browseruse_create_run, then poll browseruse_get_session or the new run's status.
Inputs
session_idstringrequired- ID of the agent session (a UUID). Every run belongs to a session; it is returned as sessionId by browseruse_create_run and browseruse_get_run, and listed by browseruse_list_sessions. Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
textstringrequired- The message for the agent, in plain language. Example: Now open the top result and summarize the comments.
interruptboolean- Set true to cancel the session's active run so this message takes effect now instead of after the current turn. Has no effect when the session is idle. Default false.
browseruse_stop_browserStop a Browser Use cloud browser.WriteStop Browser
Stop a Browser Use cloud browser. This cannot be undone, and unused paid time is refunded. Returns the browser with status stopped and finishedAt. Use this when you finish with a browser from browseruse_create_browser, or to close an agent session's browser kept open by keep_alive. Closing your CDP connection does not stop the browser. Use browseruse_cancel_run to stop an agent run.
- Idempotent
Inputs
browser_idstringrequired- ID of the cloud browser (a UUID), returned as id by browseruse_create_browser or listed by browseruse_list_browsers. Example: c4e9a1f7-5b2d-4c8e-9a3f-1d6b0e7c2a95
browseruse_update_sessionRename a Browser Use agent session.WriteRename Session
Rename a Browser Use agent session. Returns the session with its new title. Use this to label a conversation so it is easy to find in browseruse_list_sessions.
- Idempotent
Inputs
session_idstringrequired- ID of the agent session (a UUID). Every run belongs to a session; it is returned as sessionId by browseruse_create_run and browseruse_get_run, and listed by browseruse_list_sessions. Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
titlestringrequired- New name for the session, up to 255 characters. Example: Weekly competitor price check
browseruse_update_session_cost_capSet a new spending budget for a Browser Use agent session without starting a run.WriteUpdate Session Budget
Set a new spending budget for a Browser Use agent session without starting a run. Returns sessionId and maxCostUsd, the budget now applied. Use this to raise or lower the limit on model and search charges for a running or idle session. Money already spent counts against the new budget. Use browseruse_get_session_cost to see what has been spent.
- Idempotent
Inputs
max_cost_usdnumberrequired- New session budget in USD for model and search charges. Must be greater than 0. Spending so far counts against it. Example: 10
session_idstringrequired- ID of the agent session (a UUID). Every run belongs to a session; it is returned as sessionId by browseruse_create_run and browseruse_get_run, and listed by browseruse_list_sessions. Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
browseruse_delete_sessionDelete a Browser Use agent session.DestructiveDelete Session
Delete a Browser Use agent session. Any run in progress and any queued messages are cancelled first, and the session can no longer be opened or continued. Returns an empty response on success. Deleting a session twice is not an error. Use this to end and hide a conversation. Use browseruse_cancel_run to stop one run but keep the session.
- Idempotent
Inputs
session_idstringrequired- ID of the agent session (a UUID). Every run belongs to a session; it is returned as sessionId by browseruse_create_run and browseruse_get_run, and listed by browseruse_list_sessions. Example: 2b7e4c1a-9f3d-4e6b-8a2c-5d1f0e9b7a63
No tools match.
