{ "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" } } } }, "400": { "description": "Invalid request (bad session/workspace pairing or file path)." }, "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." }, "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" } } } }, "400": { "description": "Malformed pagination cursor." }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "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 — 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 — 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." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "502": { "description": "The request could not be forwarded to the control plane." } } } }, "/runs/{run_id}/events": { "get": { "tags": [ "Runs" ], "summary": "Get Run Events", "description": "Paginated event read. `after` is the event id cursor — 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" } } ], "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 — 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 — 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 — 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" } } } }, "400": { "description": "Malformed pagination cursor." }, "403": { "description": "Zero Data Retention is enabled on the project (V4 unsupported)." }, "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 — 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." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "The session message queue is full." } } }, "get": { "tags": [ "Sessions" ], "summary": "List Session Queue", "description": "List the session's still-pending queued messages, oldest first.", "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}": { "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" } } } }, "400": { "description": "Invalid request (bad session/workspace pairing or file path)." }, "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" } } } } } } }, "/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" } } } } } } }, "/workspaces/{workspace_id}/files": { "get": { "tags": [ "Workspaces" ], "summary": "List Workspace Files", "description": "List files the agent has produced for this workspace, paginated.", "operationId": "list_workspace_files_workspaces__workspace_id__files_get", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } }, { "name": "prefix", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Prefix" } }, { "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" } }, { "name": "contentDisposition", "in": "query", "required": false, "schema": { "anyOf": [ { "const": "attachment", "type": "string" }, { "type": "null" } ], "title": "Contentdisposition" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileListResponse" } } } }, "400": { "description": "Malformed pagination cursor." }, "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" } } } } } } }, "/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": "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" } } } } } } } }, "components": { "schemas": { "BrowserDownloadFile": { "properties": { "path": { "type": "string", "title": "Path", "description": "File name (basename relative to the session downloads prefix)" }, "size": { "type": "integer", "title": "Size", "description": "File size in bytes" }, "lastModified": { "type": "string", "format": "date-time", "title": "Lastmodified", "description": "When the file was last modified in S3" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Presigned download URL (15 min expiry). Only included when `includeUrls=true`." } }, "type": "object", "required": [ "path", "size", "lastModified" ], "title": "BrowserDownloadFile", "description": "A single file the browser downloaded during the session." }, "BrowserDownloadListResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/BrowserDownloadFile" }, "type": "array", "title": "Files", "description": "List of files downloaded by the browser" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor", "description": "Cursor for the next page. Pass as the `cursor` query parameter to fetch the next page." }, "hasMore": { "type": "boolean", "title": "Hasmore", "description": "Whether there are more files beyond this page.", "default": false } }, "type": "object", "required": [ "files" ], "title": "BrowserDownloadListResponse", "description": "Paginated list of browser downloads with optional presigned URLs." }, "BrowserSessionItemView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "ID", "description": "Unique identifier for the session" }, "status": { "$ref": "#/components/schemas/BrowserSessionStatus", "title": "Status", "description": "Current status of the session (active/stopped)" }, "liveUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Live URL", "description": "URL where the browser can be viewed live in real-time" }, "cdpUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "CDP URL", "description": "Chrome DevTools Protocol URL for browser automation" }, "timeoutAt": { "type": "string", "format": "date-time", "title": "Timeout At", "description": "Timestamp when the session will timeout" }, "startedAt": { "type": "string", "format": "date-time", "title": "Started At", "description": "Timestamp when the session was created and started" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At", "description": "Timestamp when the session was stopped (None if still active)" }, "proxyUsedMb": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxy Used MB", "description": "Amount of proxy data used in MB", "default": "0" }, "proxyCost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxy Cost", "description": "Cost of proxy usage in USD", "default": "0" }, "browserCost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Browser Cost", "description": "Cost of browser session hosting in USD", "default": "0" }, "agentSessionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agent Session ID", "description": "ID of the agent session that created this browser (None for standalone BaaS sessions)" }, "recordingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recording URL", "description": "Presigned URL to download the session recording. Only populated on `GET /api/v2/browsers/{id}`; always `null` in list responses." } }, "type": "object", "required": [ "id", "status", "timeoutAt", "startedAt" ], "title": "BrowserSessionItemView", "description": "View model for representing a browser session in list views." }, "BrowserSessionListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/BrowserSessionItemView" }, "type": "array", "title": "Items", "description": "List of browser session views for the current page" }, "totalItems": { "type": "integer", "title": "Total Items", "description": "Total number of items in the list" }, "pageNumber": { "type": "integer", "title": "Page Number", "description": "Page number" }, "pageSize": { "type": "integer", "title": "Page Size", "description": "Number of items per page" } }, "type": "object", "required": [ "items", "totalItems", "pageNumber", "pageSize" ], "title": "BrowserSessionListResponse", "description": "Response model for paginated browser session list requests." }, "BrowserSessionStatus": { "type": "string", "enum": [ "active", "stopped" ], "title": "BrowserSessionStatus", "description": "Enumeration of possible browser session states\n\nAttributes:\n ACTIVE: Session is currently active and running (browser is running)\n STOPPED: Session has been stopped and is no longer active (browser is stopped)" }, "BrowserSessionUpdateAction": { "type": "string", "enum": [ "stop" ], "title": "BrowserSessionUpdateAction", "description": "Available actions that can be performed on a browser session\n\nAttributes:\n STOP: Stop the browser session (cannot be undone)" }, "BrowserSessionView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "ID", "description": "Unique identifier for the session" }, "status": { "$ref": "#/components/schemas/BrowserSessionStatus", "title": "Status", "description": "Current status of the session (active/stopped)" }, "liveUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Live URL", "description": "URL where the browser can be viewed live in real-time" }, "cdpUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "CDP URL", "description": "Chrome DevTools Protocol URL for browser automation" }, "timeoutAt": { "type": "string", "format": "date-time", "title": "Timeout At", "description": "Timestamp when the session will timeout" }, "startedAt": { "type": "string", "format": "date-time", "title": "Started At", "description": "Timestamp when the session was created and started" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At", "description": "Timestamp when the session was stopped (None if still active)" }, "proxyUsedMb": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxy Used MB", "description": "Amount of proxy data used in MB", "default": "0" }, "proxyCost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Proxy Cost", "description": "Cost of proxy usage in USD", "default": "0" }, "browserCost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Browser Cost", "description": "Cost of browser session hosting in USD", "default": "0" }, "agentSessionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Agent Session ID", "description": "ID of the agent session that created this browser (None for standalone BaaS sessions)" }, "recordingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recording URL", "description": "Presigned URL to download the session recording (available after session ends, if recording was enabled)" } }, "type": "object", "required": [ "id", "status", "timeoutAt", "startedAt" ], "title": "BrowserSessionView", "description": "View model for representing a browser session." }, "CreateBrowserSessionRequest": { "properties": { "profileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Profile ID", "description": "The ID of the profile to use for the session" }, "proxyCountryCode": { "anyOf": [ { "$ref": "#/components/schemas/ProxyCountryCode" }, { "type": "null" } ], "title": "Proxy Country Code", "description": "Country code for proxy location. Defaults to US. Set to null to disable proxy.", "default": "us" }, "timeout": { "type": "integer", "title": "Timeout", "description": "The timeout for the session in minutes. All users can use up to 240 minutes (4 hours). Browser sessions are charged $0.02/hour.", "default": 60, "ge": 1, "le": 240 }, "browserScreenWidth": { "anyOf": [ { "type": "integer", "maximum": 6144, "minimum": 320 }, { "type": "null" } ], "title": "Browser Screen Width", "description": "Custom screen width in pixels for the browser." }, "browserScreenHeight": { "anyOf": [ { "type": "integer", "maximum": 3456, "minimum": 320 }, { "type": "null" } ], "title": "Browser Screen Height", "description": "Custom screen height in pixels for the browser." }, "allowResizing": { "type": "boolean", "title": "Allow Resizing", "description": "Whether to allow the browser to be resized during the session (not recommended since it reduces stealthiness).", "default": false }, "customProxy": { "anyOf": [ { "$ref": "#/components/schemas/CustomProxy" }, { "type": "null" } ], "title": "Custom Proxy", "description": "Custom proxy settings to use for the session. If not provided, our proxies will be used. Custom proxies are available on any active subscription." }, "enableRecording": { "type": "boolean", "title": "Enable Recording", "description": "If True, enables session recording. Defaults to False.", "default": false } }, "type": "object", "title": "CreateBrowserSessionRequest", "description": "Request model for creating a browser session." }, "CustomProxy": { "properties": { "host": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Host", "description": "Host of the proxy." }, "port": { "type": "integer", "maximum": 65535, "minimum": 1, "title": "Port", "description": "Port of the proxy." }, "username": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Username", "description": "Username for proxy authentication." }, "password": { "anyOf": [ { "type": "string", "maxLength": 255, "minLength": 1 }, { "type": "null" } ], "title": "Password", "description": "Password for proxy authentication." }, "ignoreCertErrors": { "type": "boolean", "title": "Ignore Certificate Errors", "description": "Ignore TLS certificate errors. Enable this if your proxy uses a self-signed or untrusted certificate (e.g. Burp Suite, corporate proxies).", "default": false } }, "type": "object", "required": [ "host", "port" ], "title": "CustomProxy", "description": "Request model for creating a custom proxy." }, "ExternalBrowserAttach": { "properties": { "cdpUrl": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Cdpurl" }, "liveViewUrl": { "anyOf": [ { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Liveviewurl" } }, "type": "object", "required": [ "cdpUrl" ], "title": "ExternalBrowserAttach", "description": "DEV-ONLY: hand v4 a pre-provisioned browser instead of having CP\ncall UseBrowserService. Gated to env=='development' in the router." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "InsufficientCreditsError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Insufficient credits" } }, "type": "object", "title": "InsufficientCreditsError", "description": "Error response when there are insufficient credits" }, "ProfileCreateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Optional name for the profile" }, "userId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User ID", "description": "Your internal user identifier for this profile. Use this to associate a profile with a user in your system." } }, "type": "object", "title": "ProfileCreateRequest", "description": "Request model for creating a new profile." }, "ProfileListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ProfileView" }, "type": "array", "title": "Items", "description": "List of profile views for the current page" }, "totalItems": { "type": "integer", "title": "Total Items", "description": "Total number of items in the list" }, "pageNumber": { "type": "integer", "title": "Page Number", "description": "Page number" }, "pageSize": { "type": "integer", "title": "Page Size", "description": "Number of items per page" } }, "type": "object", "required": [ "items", "totalItems", "pageNumber", "pageSize" ], "title": "ProfileListResponse", "description": "Response model for paginated profile list requests." }, "ProfileNotFoundError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Profile not found" } }, "type": "object", "title": "ProfileNotFoundError", "description": "Error response when a profile is not found" }, "ProfileUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name", "description": "Optional name for the profile" }, "userId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "User ID", "description": "Your internal user identifier for this profile. Use this to associate a profile with a user in your system." } }, "type": "object", "title": "ProfileUpdateRequest", "description": "Request model for updating a profile." }, "ProfileView": { "properties": { "id": { "type": "string", "format": "uuid", "title": "ID", "description": "Unique identifier for the profile" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User ID", "description": "Your internal user identifier for this profile. Use this to associate a profile with a user in your system." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Optional name for the profile" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At", "description": "Timestamp when the profile was last used" }, "createdAt": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the profile was created" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the profile was last updated" }, "cookieDomains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Cookie Domains", "description": "List of domain URLs that have cookies stored for this profile" } }, "type": "object", "required": [ "id", "createdAt", "updatedAt" ], "title": "ProfileView", "description": "View model for representing a profile. A profile lets you preserve the login state between sessions.\n\nWe recommend that you create a separate profile for each user of your app.\nYou can assign a user_id to each profile to easily identify which user the profile belongs to." }, "ProxyCountryCode": { "type": "string", "enum": [ "ad", "ae", "af", "ag", "ai", "al", "am", "an", "ao", "aq", "ar", "as", "at", "au", "aw", "az", "ba", "bb", "bd", "be", "bf", "bg", "bh", "bi", "bj", "bl", "bm", "bn", "bo", "bq", "br", "bs", "bt", "bv", "bw", "by", "bz", "ca", "cc", "cd", "cf", "cg", "ch", "ci", "ck", "cl", "cm", "co", "cr", "cs", "cu", "cv", "cw", "cx", "cy", "cz", "de", "dj", "dk", "dm", "do", "dz", "ec", "ee", "eg", "eh", "er", "es", "et", "fi", "fj", "fk", "fm", "fo", "fr", "ga", "gd", "ge", "gf", "gg", "gh", "gi", "gl", "gm", "gn", "gp", "gq", "gr", "gs", "gt", "gu", "gw", "gy", "hk", "hm", "hn", "hr", "ht", "hu", "id", "ie", "il", "im", "in", "iq", "ir", "is", "it", "je", "jm", "jo", "jp", "ke", "kg", "kh", "ki", "km", "kn", "kp", "kr", "kw", "ky", "kz", "la", "lb", "lc", "li", "lk", "lr", "ls", "lt", "lu", "lv", "ly", "ma", "mc", "md", "me", "mf", "mg", "mh", "mk", "ml", "mm", "mn", "mo", "mp", "mq", "mr", "ms", "mt", "mu", "mv", "mw", "mx", "my", "mz", "na", "nc", "ne", "nf", "ng", "ni", "nl", "no", "np", "nr", "nu", "nz", "om", "pa", "pe", "pf", "pg", "ph", "pk", "pl", "pm", "pn", "pr", "ps", "pt", "pw", "py", "qa", "re", "ro", "rs", "ru", "rw", "sa", "sb", "sc", "sd", "se", "sg", "sh", "si", "sj", "sk", "sl", "sm", "sn", "so", "sr", "ss", "st", "sv", "sx", "sy", "sz", "tc", "td", "tf", "tg", "th", "tj", "tk", "tl", "tm", "tn", "to", "tr", "tt", "tv", "tw", "tz", "ua", "ug", "uk", "us", "uy", "uz", "va", "vc", "ve", "vg", "vi", "vn", "vu", "wf", "ws", "xk", "ye", "yt", "za", "zm", "zw" ], "title": "ProxyCountryCode" }, "QueueListResponse": { "properties": { "queue": { "items": { "$ref": "#/components/schemas/QueuedMessage" }, "type": "array", "title": "Queue" } }, "type": "object", "required": [ "queue" ], "title": "QueueListResponse" }, "QueueMessageRequest": { "properties": { "text": { "type": "string", "minLength": 1, "title": "Text" }, "interrupt": { "type": "boolean", "title": "Interrupt", "default": false }, "attachedFileIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Attachedfileids" } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "QueueMessageRequest", "description": "Send a message to a session. If the session is busy the message waits on\nthe queue and runs as the next turn; if idle it runs immediately.\n\nSet `interrupt` to make it take effect now: the session's active run is\ncancelled and this message drains straight after. Interrupt is a no-op when\nthe session is already idle, and BEST-EFFORT when busy — if the cancel can't\nbe delivered, the message stays queued and runs after the current turn." }, "QueuedMessage": { "properties": { "id": { "type": "integer", "title": "Id" }, "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid" }, "runId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Runid" }, "status": { "type": "string", "enum": [ "pending", "dispatching", "consumed", "cancelled", "superseded", "failed" ], "title": "Status" }, "text": { "type": "string", "title": "Text" }, "attachedFileIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Attachedfileids" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" } }, "type": "object", "required": [ "id", "sessionId", "runId", "status", "text", "createdAt" ], "title": "QueuedMessage", "description": "One message on a session's queue (a v4_session_input row)." }, "RunAttachment": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name", "description": "Filename shown to the user, e.g. \"data.csv\"." }, "contentType": { "type": "string", "title": "Contenttype" }, "sizeBytes": { "type": "integer", "title": "Sizebytes" }, "status": { "type": "string", "enum": [ "pending", "uploaded" ], "title": "Status", "description": "\"pending\" | \"uploaded\"." } }, "type": "object", "required": [ "id", "name", "contentType", "sizeBytes", "status" ], "title": "RunAttachment" }, "RunAttachmentsResponse": { "properties": { "attachments": { "items": { "$ref": "#/components/schemas/RunAttachment" }, "type": "array", "title": "Attachments" } }, "type": "object", "required": [ "attachments" ], "title": "RunAttachmentsResponse" }, "RunBrowserSettings": { "properties": { "profileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Profileid", "description": "ID of a browser profile to load into the session. Profiles persist cookies, local storage, and other browser state across sessions." }, "proxyCountryCode": { "anyOf": [ { "$ref": "#/components/schemas/ProxyCountryCode" }, { "type": "null" } ], "description": "ISO country code to proxy the browser through. Defaults to US. Pass null to run without a proxy.", "default": "us" }, "customProxy": { "anyOf": [ { "$ref": "#/components/schemas/CustomProxy" }, { "type": "null" } ], "description": "Custom proxy for the browser. Overrides proxyCountryCode. Requires an active subscription. Never stored or inherited by follow-up runs; pass it on each run that should use it." }, "screenWidth": { "anyOf": [ { "type": "integer", "maximum": 6144, "minimum": 320 }, { "type": "null" } ], "title": "Screenwidth", "description": "Custom screen width in pixels for the browser." }, "screenHeight": { "anyOf": [ { "type": "integer", "maximum": 3456, "minimum": 320 }, { "type": "null" } ], "title": "Screenheight", "description": "Custom screen height in pixels for the browser." }, "record": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Record", "description": "Record the browser session to an mp4, retrievable via GET /browsers/{id} once the browser stops. API runs default to off; pass true to enable. Like other browser settings, this only applies when a new browser is provisioned: a follow-up that reuses the session's live browser keeps that browser's recording state. Ignored (always off) for Zero Data Retention projects." } }, "additionalProperties": false, "type": "object", "title": "RunBrowserSettings", "description": "Browser config, owned by the browser row (never the run). Follow-ups:\nomitted fields inherit the session's prior browser; explicit values apply\nonly to newly provisioned browsers (a live browser is reused as-is).\nProfile is the exception: a different profile → 400; an explicit value\nmismatching the live browser's profile (incl. null vs a profiled browser)\ndeclines reuse and provisions fresh. A live browser already matching the\nrequested profile is reused." }, "RunCreateRequest": { "properties": { "task": { "type": "string", "minLength": 1, "title": "Task" }, "model": { "type": "string", "enum": [ "glm-5.2", "grok-4.5", "kimi-k3", "minimax-m3", "claude-opus-4.7", "claude-opus-4.8", "claude-opus-5", "claude-fable-5", "claude-sonnet-5", "gpt-5.5", "gpt-5.6", "gemini-3.5-flash", "gemini-3.1-pro", "gemini-3-flash" ], "title": "Model", "default": "minimax-m3" }, "sessionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Sessionid" }, "workspaceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspaceid" }, "browserSettings": { "anyOf": [ { "$ref": "#/components/schemas/RunBrowserSettings" }, { "type": "null" } ] }, "attachedFileIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Attachedfileids" }, "judge": { "anyOf": [ { "$ref": "#/components/schemas/RunJudgeSettings" }, { "type": "null" } ] }, "maxCostUsd": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Maxcostusd" } }, "additionalProperties": false, "type": "object", "required": [ "task" ], "title": "RunCreateRequest" }, "RunCreateResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "model": { "type": "string", "title": "Model" }, "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid" }, "workspaceId": { "type": "string", "format": "uuid", "title": "Workspaceid" }, "eventsUrl": { "type": "string", "title": "Eventsurl" }, "missingFileIds": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Missingfileids" } }, "type": "object", "required": [ "id", "status", "model", "sessionId", "workspaceId", "eventsUrl" ], "title": "RunCreateResponse" }, "RunEvent": { "properties": { "runId": { "type": "string", "format": "uuid", "title": "Runid" }, "id": { "type": "integer", "title": "Id" }, "ts": { "type": "string", "format": "date-time", "title": "Ts" }, "type": { "type": "string", "title": "Type" }, "data": { "additionalProperties": true, "type": "object", "title": "Data" } }, "type": "object", "required": [ "runId", "id", "ts", "type", "data" ], "title": "RunEvent" }, "RunEventsResponse": { "properties": { "events": { "items": { "$ref": "#/components/schemas/RunEvent" }, "type": "array", "title": "Events" }, "nextAfter": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nextafter" }, "hasMore": { "type": "boolean", "title": "Hasmore", "default": false } }, "type": "object", "required": [ "events" ], "title": "RunEventsResponse" }, "RunJudgeSettings": { "properties": { "context": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ], "title": "Context" } }, "additionalProperties": false, "type": "object", "title": "RunJudgeSettings", "description": "Opt-in LLM judgement of the finished run. Presence of this object turns\nthe judge on (send {} for defaults); CP judges the run's trajectory after\nit goes terminal and surfaces the verdict as RunSummary.judgement (null\nuntil it lands). The judge's LLM call is billed to the run." }, "RunListResponse": { "properties": { "runs": { "items": { "$ref": "#/components/schemas/RunSummary" }, "type": "array", "title": "Runs" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" }, "hasMore": { "type": "boolean", "title": "Hasmore", "default": false } }, "type": "object", "required": [ "runs" ], "title": "RunListResponse" }, "RunStatusResponse": { "properties": { "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled" ], "title": "Status" } }, "type": "object", "required": [ "status" ], "title": "RunStatusResponse", "description": "Minimal poll target: just the run's status. Poll this until terminal\n(cheap indexed lookup, tiny payload — never the task/result text), then\nfetch the full RunSummary once via GET /runs/{id}. Mirrors v2's\nGET /tasks/{id}/status." }, "RunSummary": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "task": { "type": "string", "title": "Task" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "model": { "type": "string", "title": "Model" }, "contextLimit": { "type": "integer", "title": "Contextlimit" }, "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" }, "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid" }, "workspaceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspaceid" }, "attachedFileIds": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Attachedfileids" }, "judgement": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Judgement" }, "totalInputTokens": { "type": "integer", "title": "Totalinputtokens" }, "totalOutputTokens": { "type": "integer", "title": "Totaloutputtokens" }, "totalCostUsd": { "type": "string", "title": "Totalcostusd" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "task", "title", "model", "contextLimit", "status", "result", "error", "sessionId", "workspaceId", "totalInputTokens", "totalOutputTokens", "totalCostUsd", "createdAt", "updatedAt" ], "title": "RunSummary" }, "SessionInfo": { "properties": { "sessionId": { "type": "string", "format": "uuid", "title": "Sessionid" }, "workspaceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Workspaceid" }, "latestRunId": { "type": "string", "format": "uuid", "title": "Latestrunid" }, "task": { "type": "string", "title": "Task" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title" }, "status": { "type": "string", "enum": [ "queued", "dispatching", "running", "completed", "failed", "cancelled" ], "title": "Status" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "sessionId", "workspaceId", "latestRunId", "task", "title", "status", "createdAt", "updatedAt" ], "title": "SessionInfo", "description": "Lightweight metadata for one V4 session (its most recent run).\n\nDeliberately slim — just what a session list needs (open the conversation,\nshow a label + status + time). The heavy per-run fields (result, error,\ntoken/cost totals) live on RunSummary and aren't repeated here." }, "SessionListResponse": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/SessionInfo" }, "type": "array", "title": "Sessions" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" }, "hasMore": { "type": "boolean", "title": "Hasmore", "default": false } }, "type": "object", "required": [ "sessions" ], "title": "SessionListResponse", "description": "One entry per session (the session's most recent run), most-recent first.\n\nA V4 session is a conversation: every follow-up run reuses the same\npublic_session_id. GET /api/v4/runs returns one row per RUN, so callers that\nwant a list of distinct *sessions* (e.g. the recent-sessions panel) should\nuse this instead of de-duplicating runs client-side." }, "SessionNotFoundError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Session not found" } }, "type": "object", "title": "SessionNotFoundError", "description": "Error response when a session is not found" }, "SessionTimeoutLimitExceededError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Maximum session timeout is 4 hours (240 minutes)." } }, "type": "object", "title": "SessionTimeoutLimitExceededError", "description": "Error response when session timeout exceeds the maximum allowed limit" }, "TooManyConcurrentActiveSessionsError": { "properties": { "detail": { "type": "string", "title": "Detail", "default": "Too many concurrent active sessions. Please wait for one to finish, kill one, or upgrade your plan." } }, "type": "object", "title": "TooManyConcurrentActiveSessionsError", "description": "Error response when user has too many concurrent active sessions" }, "UpdateBrowserSessionRequest": { "properties": { "action": { "$ref": "#/components/schemas/BrowserSessionUpdateAction", "title": "Action", "description": "The action to perform on the session" } }, "type": "object", "required": [ "action" ], "title": "UpdateBrowserSessionRequest", "description": "Request model for updating browser session state." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "WorkspaceCreateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "Name" } }, "type": "object", "title": "WorkspaceCreateRequest" }, "WorkspaceFileInfo": { "properties": { "path": { "type": "string", "title": "Path", "description": "File path relative to the workspace root" }, "size": { "type": "integer", "title": "Size", "description": "File size in bytes" }, "lastModified": { "type": "string", "format": "date-time", "title": "Lastmodified", "description": "When the file was last modified" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Presigned download URL (60s expiry). Only included when `includeUrls=true`." } }, "type": "object", "required": [ "path", "size", "lastModified" ], "title": "WorkspaceFileInfo", "description": "A file the agent has produced for the workspace. Shape mirrors V3\nfiles (FileInfo) so a single UI component can render both." }, "WorkspaceFileListResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/WorkspaceFileInfo" }, "type": "array", "title": "Files" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nextcursor" }, "hasMore": { "type": "boolean", "title": "Hasmore", "default": false } }, "type": "object", "required": [ "files" ], "title": "WorkspaceFileListResponse" }, "WorkspaceFileUploadItem": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "Filename, e.g. \"data.csv\"" }, "contentType": { "type": "string", "maxLength": 255, "title": "Contenttype", "description": "MIME type, e.g. \"text/csv\"", "default": "application/octet-stream" }, "size": { "type": "integer", "maximum": 52428800, "minimum": 1, "title": "Size", "description": "Exact file size in bytes; the presigned URL is pinned to it." } }, "type": "object", "required": [ "name", "size" ], "title": "WorkspaceFileUploadItem" }, "WorkspaceFileUploadRequest": { "properties": { "files": { "items": { "$ref": "#/components/schemas/WorkspaceFileUploadItem" }, "type": "array", "maxItems": 10, "minItems": 1, "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "WorkspaceFileUploadRequest" }, "WorkspaceFileUploadResponse": { "properties": { "files": { "items": { "$ref": "#/components/schemas/WorkspaceFileUploadResponseItem" }, "type": "array", "title": "Files" } }, "type": "object", "required": [ "files" ], "title": "WorkspaceFileUploadResponse" }, "WorkspaceFileUploadResponseItem": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Upload id. Pass THIS in RunCreateRequest.attachedFileIds to attach the file to a run." }, "name": { "type": "string", "title": "Name", "description": "Original filename from the request" }, "storedName": { "type": "string", "title": "Storedname", "description": "Sanitized filename the object is stored under, e.g. \"data.csv\"." }, "path": { "type": "string", "title": "Path", "description": "Path within the workspace, e.g. \"uploads/data.csv\"" }, "willOverride": { "type": "boolean", "title": "Willoverride", "description": "True if a file with this stored_name already exists in the workspace and uploading will replace it. Surface a warning to the user." }, "uploadUrl": { "type": "string", "title": "Uploadurl", "description": "Presigned PUT URL (5 min expiry). PUT the file bytes with the matching Content-Type and Content-Length headers." } }, "type": "object", "required": [ "id", "name", "storedName", "path", "willOverride", "uploadUrl" ], "title": "WorkspaceFileUploadResponseItem" }, "WorkspaceInfo": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "archived": { "type": "boolean", "title": "Archived" }, "createdAt": { "type": "string", "format": "date-time", "title": "Createdat" }, "updatedAt": { "type": "string", "format": "date-time", "title": "Updatedat" } }, "type": "object", "required": [ "id", "archived", "createdAt", "updatedAt" ], "title": "WorkspaceInfo" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Browser-Use-API-Key" } } } }