Every API here is available over the APIs.io API and to AI agents over MCP.
{
"openapi": "3.1.0",
"info": {
"title": "Browser Use Public API v4",
"summary": "Browser Use agent runs API (v4)",
"version": "4.0.0"
},
"servers": [
{
"url": "https://api.browser-use.com/api/v4",
"description": "Production server"
}
],
"paths": {
"/runs": {
"post": {
"tags": [
"Runs"
],
"summary": "Create Run",
"operationId": "create_run_runs_post",
"security": [
{
"APIKeyHeader": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunCreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunCreateResponse"
}
}
}
},
"402": {
"description": "The project has no credits available."
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"409": {
"description": "The session already has an active run."
},
"400": {
"description": "Invalid request (bad session/workspace pairing or file path)."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get": {
"tags": [
"Runs"
],
"summary": "List Runs",
"operationId": "list_runs_runs_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 50,
"title": "Limit"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Keyset cursor from a prior response.",
"title": "Cursor"
},
"description": "Keyset cursor from a prior response."
},
{
"name": "sessionId",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Sessionid"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunListResponse"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"400": {
"description": "Malformed pagination cursor."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/runs/{run_id}/attachments": {
"get": {
"tags": [
"Runs"
],
"summary": "List Run Attachments",
"description": "The upload files attached to a run, for rendering attachment chips.\nOrdered to match the run's attached_file_ids.",
"operationId": "list_run_attachments_runs__run_id__attachments_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Run Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunAttachmentsResponse"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/runs/{run_id}": {
"get": {
"tags": [
"Runs"
],
"summary": "Get Run",
"operationId": "get_run_runs__run_id__get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Run Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunSummary"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/runs/{run_id}/status": {
"get": {
"tags": [
"Runs"
],
"summary": "Get Run Status",
"description": "Minimal status poll (see RunStatusResponse). POLL rate bucket: selects\nONLY the status/project columns \u2014 a 2s poll never drags the task/result\ntext (TOAST reads) that GET /runs/{id} pays. Poll until terminal, then\nfetch the full summary once.",
"operationId": "get_run_status_runs__run_id__status_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Run Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunStatusResponse"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/runs/{run_id}/cancel": {
"post": {
"tags": [
"Runs"
],
"summary": "Cancel Run",
"description": "Cancel an in-flight run.\n\nIdempotent: a run already in a terminal state (completed / failed /\ncancelled) is returned as-is. Once cancelled, the gateway refuses\nevery subsequent `chat_completions` call from the worker \u2014 so the\nproject cannot be billed further regardless of whether the worker\nsubprocess notices the cancel itself.\n\nThe worker keeps running for at most one more bcode step\n(consuming no LLM tokens because CP 409s them) and then exits when\nbcode realizes the next tool call has no model behind it.",
"operationId": "cancel_run_runs__run_id__cancel_post",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Run Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunSummary"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"502": {
"description": "The request could not be forwarded to the control plane."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/runs/{run_id}/events": {
"get": {
"tags": [
"Runs"
],
"summary": "Get Run Events",
"description": "Paginated event read. `after` is the event id cursor \u2014 clients\ndoing periodic polls pass back the highest id they've seen to get only\nthe delta. Default 0 returns from the start.",
"operationId": "get_run_events_runs__run_id__events_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Run Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 200,
"title": "Limit"
}
},
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 0,
"title": "After"
}
},
{
"name": "include_output",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": true,
"title": "Include Output"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunEventsResponse"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/sessions": {
"get": {
"tags": [
"Sessions"
],
"summary": "List Sessions",
"description": "List the project's V4 sessions \u2014 one row per session (its most recent\nrun), most-recent first.\n\nA session is a conversation: follow-up runs reuse the same\npublic_session_id, so GET /api/v4/runs would list one row per RUN. This\ncollapses to one row per SESSION directly in Postgres with DISTINCT ON, so a\nchatty session with 100 runs is still a single row (no scan amplification),\nand selects only the slim columns the session list needs \u2014 never the heavy\nper-run text/token/cost fields.\n\nKeyset-paginated on the latest run's (created_at, id): pass `next_cursor`\nback as `cursor` to page. Offset/COUNT was dropped \u2014 it doesn't scale on\nprojects with many sessions.",
"operationId": "list_sessions_sessions_get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Max sessions per page (max 100).",
"default": 20,
"title": "Limit"
},
"description": "Max sessions per page (max 100)."
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Keyset cursor from a prior response.",
"title": "Cursor"
},
"description": "Keyset cursor from a prior response."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionListResponse"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"400": {
"description": "Malformed pagination cursor."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/sessions/{session_id}/purge": {
"post": {
"tags": [
"Sessions"
],
"summary": "Purge Session",
"description": "Immediately purge all data for a V4 session (ZDR projects only).\n\nRedacts DB records and deletes S3 objects (bcode state, workspace files,\nrecordings, downloads, staging uploads) for every run in the session. Same\ncleanup the ZDR cron performs, but on-demand and with no grace period. V4\nanalog of the V2 POST /sessions/{id}/purge. Surfaces shared with a still-live\nsibling run are deferred by the same guards the cron uses.",
"operationId": "purge_session_sessions__session_id__purge_post",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"403": {
"description": "Project is not ZDR-enabled."
},
"404": {
"description": "Session not found."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/sessions/{session_id}": {
"get": {
"tags": [
"Sessions"
],
"summary": "Get Session",
"description": "Session detail \u2014 the same slim shape as one GET /sessions row (its\nlatest run). Doubles as the busy/idle poll for a conversation (POLL rate\nbucket): slim columns only, indexed public_session_id lookup, never the\nheavy result/token fields.",
"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/SessionInfo"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/sessions/{session_id}/queue": {
"post": {
"tags": [
"Sessions"
],
"summary": "Queue Session Message",
"description": "Send a message to a session. If the session is busy it waits on the queue\nand runs as the next turn; if idle it drains immediately.\n\n`interrupt=true` cancels the session's active run so this message takes effect\nnow instead of waiting for the current turn (no-op when the session is idle).",
"operationId": "queue_session_message_sessions__session_id__queue_post",
"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/QueueMessageRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueuedMessage"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"429": {
"description": "The session message queue is full."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get": {
"tags": [
"Sessions"
],
"summary": "List Session Queue",
"description": "List open messages, the latest handoff row, and all steering cutoffs.\n\nIncludes live dispatch claims so clients can restore an accepted steering\nhandoff after a refresh without briefly losing its waiting state. The latest\nconsumed interrupt bridges the primary-write/read-replica gap before its\nreplacement run appears; clients discard it once that run is visible. Compact\nper-source cutoffs preserve every historical interrupted transcript boundary\nwithout returning every historical steering message and its attachments.",
"operationId": "list_session_queue_sessions__session_id__queue_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/QueueListResponse"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/sessions/{session_id}/queue/{message_id}": {
"get": {
"tags": [
"Sessions"
],
"summary": "Get Session Queue Message",
"description": "Read one queued message including terminal handoff states.",
"operationId": "get_session_queue_message_sessions__session_id__queue__message_id__get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
},
{
"name": "message_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"title": "Message Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueuedMessage"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Sessions"
],
"summary": "Cancel Queued Message",
"description": "Remove a still-pending queued message; 409 once the drain has claimed it.",
"operationId": "cancel_queued_message_sessions__session_id__queue__message_id__delete",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Session Id"
}
},
{
"name": "message_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"title": "Message Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueuedMessage"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"409": {
"description": "The message is no longer pending and cannot be cancelled."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/workspaces": {
"post": {
"tags": [
"Workspaces"
],
"summary": "Create Workspace",
"description": "Mint an empty workspace. Lets callers upload input files BEFORE the\nfirst run exists; pass the id as workspaceId on POST /runs.",
"operationId": "create_workspace_workspaces_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceCreateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceInfo"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"APIKeyHeader": []
}
]
}
},
"/workspaces/{workspace_id}/files/upload": {
"post": {
"tags": [
"Workspaces"
],
"summary": "Upload Workspace Files",
"description": "Presigned PUT URLs for input files, placed under ``uploads/`` in the\nworkspace. The agent pulls them in at the start of every run. URLs are\npinned to the declared Content-Type and exact Content-Length.",
"operationId": "upload_workspace_files_workspaces__workspace_id__files_upload_post",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Workspace Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceFileUploadRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceFileUploadResponse"
}
}
}
},
"403": {
"description": "Zero Data Retention is enabled on the project (V4 unsupported)."
},
"404": {
"description": "Run, session, workspace, or profile not found."
},
"400": {
"description": "Invalid request (bad session/workspace pairing or file path)."
},
"409": {
"description": "One or more files would replace existing workspace files."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/workspaces/{workspace_id}": {
"get": {
"tags": [
"Workspaces"
],
"summary": "Get Workspace",
"operationId": "get_workspace_workspaces__workspace_id__get",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Workspace Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceInfo"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Workspaces"
],
"summary": "Update Workspace",
"description": "Rename a workspace. Explicit null clears the name; omission is a no-op.",
"operationId": "update_workspace_workspaces__workspace_id__patch",
"security": [
{
"APIKeyHeader": []
}
],
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Workspace Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceUpdateRequest"
}
}
}
# --- truncated at 32 KB (127 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/browser-use/refs/heads/main/openapi/browser-use-api-v4-openapi.json