The session-based Browser Use Cloud REST API — agent sessions with streamed messages, standalone CDP browsers, persistent workspaces and files, browser profiles, billing account balance, and an x402 machine-payment balance endpoint. 27 operations, OpenAPI 3.1.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/browser-use-api-v3"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
{
"openapi": "3.1.0",
"info": {
"title": "Browser Use Public API v3",
"summary": "Browser Use session-based agent API (v3)",
"version": "3.0.0"
},
"servers": [
{
"url": "https://api.browser-use.com/api/v3",
"description": "Production server"
}
],
"paths": {
"/sessions": {
"post": {
"tags": [
"Sessions"
],
"summary": "Create Session",
"description": "Create a session and/or dispatch a task.\n\n- Without session_id, without task: creates a new idle session (e.g. for file uploads).\n- Without session_id, with task: creates a new session and dispatches the task.\n- With session_id, with task: dispatches the task to an existing idle session.\n- With session_id, without task: 422 \u2014 task is required when targeting an existing session.\n\nIf keep_alive is false (default), the session auto-stops when the task finishes.\nIf keep_alive is true, the session stays idle after the task, ready for follow-ups.",
"operationId": "create_session_sessions_post",
"security": [
{
"APIKeyHeader": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunTaskRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get": {
"tags": [
"Sessions"
],
"summary": "List Sessions",
"description": "List sessions for the authenticated project.\n\nList responses intentionally omit per-session presigned URLs\n(`screenshot_url`, `recording_urls`). Each presign is a synchronous boto3\nSigV4 signing call that holds the GIL and blocks the event loop. With\npage_size up to 100 this CPU-pegs the worker and starves the DB pool,\ncascading into pool exhaustion across the fleet. Clients should fetch\nthese URLs on demand via `GET /api/v3/sessions/{id}`, which signs exactly\none screenshot URL plus any recording URLs for a single session.",
"operationId": "list_sessions_sessions_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number (1-indexed).",
"default": 1,
"title": "Page"
},
"description": "Page number (1-indexed)."
},
{
"name": "page_size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Number of sessions per page (max 100).",
"default": 20,
"title": "Page Size"
},
"description": "Number of sessions per page (max 100)."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/sessions/{session_id}": {
"get": {
"tags": [
"Sessions"
],
"summary": "Get Session",
"description": "Get session details. Use this to poll for task completion and output.",
"operationId": "get_session_sessions__session_id__get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Sessions"
],
"summary": "Delete Session",
"description": "Soft-delete a session. Stops the sandbox first if still running.",
"operationId": "delete_session_sessions__session_id__delete",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/sessions/{session_id}/stop": {
"post": {
"tags": [
"Sessions"
],
"summary": "Stop Session",
"description": "Stop a session or the running task.\n\n- strategy=session (default): destroy sandbox entirely, session \u2192 stopped.\n- strategy=task: stop the running query, session stays alive (\u2192 idle).",
"operationId": "stop_session_sessions__session_id__stop_post",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/StopSessionRequest"
},
{
"type": "null"
}
],
"title": "Body"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/sessions/{session_id}/messages": {
"get": {
"tags": [
"Sessions"
],
"summary": "List Session Messages",
"description": "Return messages for a session with cursor-based pagination (chronological order).",
"operationId": "list_session_messages_sessions__session_id__messages_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
},
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Cursor: return messages after this message ID",
"title": "After"
},
"description": "Cursor: return messages after this message ID"
},
{
"name": "before",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Cursor: return messages before this message ID",
"title": "Before"
},
"description": "Cursor: return messages before this message ID"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Maximum number of messages to return (max 100).",
"default": 10,
"title": "Limit"
},
"description": "Maximum number of messages to return (max 100)."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/browsers": {
"get": {
"tags": [
"Browsers"
],
"summary": "List Browser Sessions",
"description": "Get paginated list of browser sessions with optional status filtering.\n\nList responses intentionally omit per-session presigned recording URLs\n(`recording_url` is always `null` here). Each recording URL requires a\nsynchronous boto3 SigV4 signing call (plus an S3 HEAD) that holds the GIL\nand blocks the event loop. With page_size up to the max this CPU-pegs the\nworker and starves the DB pool, cascading into pool exhaustion across the\nfleet. Clients should fetch the recording URL on demand via\n`GET /api/v2/browsers/{id}`, which signs exactly one URL for a single\nsession. Mirrors the v3 sessions list fix (ENG-4904, PR #4621).",
"operationId": "list_browser_sessions_browsers_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "metadata",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Only browsers tagged with every one of these terms. `key` matches any value; `key=value` matches exactly. Repeat the param to require more than one (AND).",
"title": "Metadata"
},
"description": "Only browsers tagged with every one of these terms. `key` matches any value; `key=value` matches exactly. Repeat the param to require more than one (AND)."
},
{
"name": "pageSize",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 10,
"title": "Pagesize"
}
},
{
"name": "pageNumber",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"default": 1,
"title": "Pagenumber"
}
},
{
"name": "filterBy",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/BrowserSessionStatus"
},
{
"type": "null"
}
],
"title": "Filterby"
}
},
{
"name": "agentSessionId",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Agentsessionid"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserSessionListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Browsers"
],
"summary": "Create Browser Session",
"description": "Create a new browser session.\n\n**Pricing:** Browser sessions are charged at $0.02/hour for all users.\n\nThe full rate is charged upfront when the session starts.\nWhen you stop the session, any unused time is automatically refunded proportionally.\n\nBilling is rounded up to the minute (minimum 1 minute).\nFor example, if you stop a session after 30 minutes, you'll be refunded half the charged amount.\n\n**Session Limits:**\n- All users: Up to 4 hours per session",
"operationId": "create_browser_session_browsers_post",
"security": [
{
"APIKeyHeader": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBrowserSessionRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserSessionItemView"
}
}
}
},
"403": {
"description": "Session timeout limit exceeded (maximum 4 hours)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionTimeoutLimitExceededError"
}
}
}
},
"404": {
"description": "Profile not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileNotFoundError"
}
}
}
},
"422": {
"description": "Request validation failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationError"
}
}
}
},
"429": {
"description": "Too many concurrent active sessions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TooManyConcurrentActiveSessionsError"
}
}
}
}
}
}
},
"/browsers/{session_id}": {
"get": {
"tags": [
"Browsers"
],
"summary": "Get Browser Session",
"description": "Get detailed browser session information including status and URLs.",
"operationId": "get_browser_session_browsers__session_id__get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserSessionView"
}
}
}
},
"404": {
"description": "Session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionNotFoundError"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Browsers"
],
"summary": "Update Browser Session",
"description": "Stop a browser session.\n\n**Refund:** When you stop a session, unused time is automatically refunded.\nIf the session ran for less than 1 hour, you'll receive a proportional refund.\nBilling is ceil to the nearest minute (minimum 1 minute).",
"operationId": "update_browser_session_browsers__session_id__patch",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateBrowserSessionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserSessionView"
}
}
}
},
"404": {
"description": "Session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionNotFoundError"
}
}
}
},
"422": {
"description": "Request validation failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationError"
}
}
}
}
}
}
},
"/browsers/{session_id}/downloads": {
"get": {
"tags": [
"Browsers"
],
"summary": "List Browser Session Downloads",
"description": "List files the browser downloaded to S3 during the session.\n\nPass ``includeUrls=true`` to receive presigned download URLs (15 min expiry) inline.\nFiles are stored at ``downloads/projects/{project_id}/sessions/{session_id}/`` in\nthe private bucket.",
"operationId": "list_browser_session_downloads_browsers__session_id__downloads_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 50,
"title": "Limit"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor"
}
},
{
"name": "includeUrls",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "Includeurls"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BrowserDownloadListResponse"
}
}
}
},
"404": {
"description": "Session not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionNotFoundError"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/profiles": {
"get": {
"tags": [
"Profiles"
],
"summary": "List Profiles",
"description": "Get paginated list of profiles.\n\nUse the `query` parameter to search profiles by name or user_id.\nThis is useful when you have many profiles and need to find a specific user.\n\nExample: If you set `user_id` to your internal user identifier when creating profiles,\nyou can later search for that user by passing their identifier as the `query` parameter.",
"operationId": "list_profiles_profiles_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "pageSize",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 10,
"title": "Pagesize"
}
},
{
"name": "pageNumber",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"default": 1,
"title": "Pagenumber"
}
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"title": "Query"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Profiles"
],
"summary": "Create Profile",
"description": "Profiles allow you to preserve the state of the browser between tasks.\n\nThey are most commonly used to allow users to preserve the log-in state in the agent between tasks.\nYou'd normally create one profile per user and then use it for all their tasks.\n\nYou can set a `user_id` when creating a profile to associate it with a user in your system.\nThis allows you to later search for the profile using the GET /profiles endpoint with a query parameter.",
"operationId": "create_profile_profiles_post",
"security": [
{
"APIKeyHeader": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileCreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileView"
}
}
}
},
"402": {
"description": "Subscription required for additional profiles",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InsufficientCreditsError"
}
}
}
},
"422": {
"description": "Request validation failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationError"
}
}
}
}
}
}
},
"/profiles/{profile_id}": {
"get": {
"tags": [
"Profiles"
],
"summary": "Get Profile",
"description": "Get profile details.",
"operationId": "get_profile_profiles__profile_id__get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "profile_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Profile Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileView"
}
}
}
},
"404": {
"description": "Profile not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileNotFoundError"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Profiles"
],
"summary": "Update Profile",
"description": "Update a browser profile's information.",
"operationId": "update_profile_profiles__profile_id__patch",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "profile_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Profile Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileUpdateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileView"
}
}
}
},
"404": {
"description": "Profile not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProfileNotFoundError"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Profiles"
],
"summary": "Delete Browser Profile",
"description": "Permanently delete a browser profile and its configuration.",
"operationId": "delete_browser_profile_profiles__profile_id__delete",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "profile_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Profile Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/workspaces": {
"get": {
"tags": [
"Workspaces"
],
"summary": "List
# --- truncated at 32 KB (123 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/browser-use/refs/heads/main/openapi/browser-use-api-v3-openapi.json