One API key, full browser automation
Suprbrowser is a browser automation API for AI agents. Send a natural language task, and an AI agent navigates the web autonomously: clicks, types, solves CAPTCHAs, downloads files, and extracts structured data.
No browser provider accounts required. Suprbrowser manages all provider relationships (Anchor, CapSolver, SMS providers). You only need your API key.
Every session returns a live preview URL, streams real-time events via SSE, and supports mid-session steering. 1 credit per browser action.
Available as a REST API, Python SDK, TypeScript SDK, and MCP server.
Step 1: Get your API key
Create a key in the API Keys tab. It starts with omk_ and works for all Suprbrowser sessions.
Step 2: Start your first session
pip install suprbrowser
from suprbrowser import Suprbrowser
client = Suprbrowser("omk_your_key")
session = await client.browse("Search Google for 'best browser automation API' and extract top 5 results")
print(session.live_view_url) # Watch the browser in real timenpm install suprbrowser
import { Suprbrowser } from "suprbrowser";
const client = new Suprbrowser("omk_your_key");
const session = await client.browse("Search Google for 'best browser automation API' and extract top 5 results");
console.log(session.live_view_url);{
"suprbrowser": {
"command": "npx",
"args": ["-y", "suprbrowser-mcp"],
"env": { "SUPRBROWSER_API_KEY": "omk_your_key" }
}
}curl -X POST https://suprbrowser.ai/v1/sessions \
-H "Authorization: Bearer omk_your_key" \
-H "Content-Type: application/json" \
-d '{"task": "Search Google for best browser automation API and extract top 5 results"}'All four methods hit the same API, use the same key, and deduct from the same credit balance.
API key authentication and rate limits
Suprbrowser uses Bearer token authentication. Include your API key in the Authorization header of every request.
Authorization: Bearer omk_your_key_hereAPI keys are created in the API Keys section. Your key works for all browser automation sessions and is tied to your account and credit balance. Keys can be revoked at any time.
Rate limits
Default: 60 requests per minute per key. Rate limit headers are included in every response:
X-RateLimit-Remaining: 58
X-RateLimit-Limit: 60
X-RateLimit-Reset: 1713400060
X-Credits-Used: 2Per-capability credit pricing
1 credit = 1 browser action. Every action the agent takes (click, type, navigate, solve CAPTCHA, extract data) costs 1 credit. Failed sessions are free.
/v1/sessions
1 creditLaunch an AI-driven browser session with a natural language task
/v1/sessions
0 creditsList browser automation sessions with optional filters
/v1/sessions/{session_id}
0 creditsGet session status, progress, and live view URL
/v1/sessions/{session_id}/stop
0 creditsStop a running browser automation session immediately
/v1/sessions/{session_id}/pause
0 creditsPause a running session while keeping the browser alive
/v1/sessions/{session_id}/resume
0 creditsResume a paused browser session
/v1/sessions/{session_id}/steer
0 creditsSend a mid-session correction to the running agent
/v1/sessions/{session_id}/deliverables
0 creditsGet all structured data extracted during the session
/v1/sessions/{session_id}/files
0 creditsList all files created during the session
/v1/files/{file_id}
0 creditsGet file metadata for a specific file
/v1/profiles
0 creditsCreate a persistent browser profile with sticky IP
/v1/profiles
0 creditsList all browser profiles
/v1/profiles/{profile_id}
0 creditsDelete a browser profile and its persistent state
Credits are returned in the credits_used field and the X-Credits-Used response header.
Error handling and status codes
All errors follow RFC 7807 (Problem Details for HTTP APIs) with additional fields for agent consumption.
{
"success": false,
"error": {
"type": "https://api.o-mega.ai/errors/rate-limited",
"title": "Rate limit exceeded",
"status": 429,
"detail": "You have exceeded 60 requests per minute",
"is_retriable": true,
"retry_after_seconds": 42,
"alternative_action": "Reduce request frequency or contact support",
"error_category": "transient"
},
"credits_used": 0
}Error categories
Temporary issue. Safe to retry after retry_after_seconds.
Request is invalid. Do not retry with the same parameters.
API key is missing, invalid, or revoked.
Insufficient credits. Upgrade plan or enable overage.
The target content could not be accessed (blocked, CAPTCHA, etc).
HTTP status codes
Success. The request completed and data is in the response.
Bad request. Missing or invalid parameters.
Unauthorized. API key is missing or invalid.
Insufficient credits. Upgrade or enable overage.
Unprocessable. The request was valid but the operation failed (e.g. scrape blocked).
Rate limited. Retry after the specified interval.
Provider error. All upstream providers failed.
Unified response envelope
Every response uses the same format. This makes it easy for agents to parse responses uniformly.
{
"success": boolean,
"data": { ... } | null,
"error": { ... } | null,
"metadata": {
"response_time_ms": number,
"request_id": "string"
},
"credits_used": number
}Metadata fields
response_time_ms
number
Total wall-clock time for the request in milliseconds.
request_id
string
Unique request identifier for debugging and support.
Official packages for every integration method
Every package uses the same API key and hits the same backend. Pick whichever fits your stack.
MCP Server
$ npx suprbrowser-mcpWorks with Claude Desktop, Cursor, VS Code. Gives your agent a browser automation tool.
Python SDK
$ pip install suprbrowserFor LangChain, CrewAI, OpenAI Agents SDK, Claude API, or any Python agent.
TypeScript SDK
$ npm install suprbrowserFor Vercel AI SDK, LangChain.js, Node.js agents, or any TypeScript project.
REST API
Works with any language or framework. Use curl or any HTTP client with a Bearer token.
Machine-readable formats
For auto-generating clients or configuring agent frameworks:
OpenAPI spec
/v1/openapi.json?product=suprbrowserFiltered OpenAPI 3.1 spec with only Suprbrowser endpoints.
Tool definitions
/v1/tools?product=suprbrowser&format=openaiPre-built tool schemas for OpenAI, Claude, and MCP. Formats: openai, claude, mcp, raw.
llms.txt
/llms.txtAI-readable documentation index for agent discovery.
Real-time session events via SSE
Every session supports Server-Sent Events (SSE) for real-time progress. Connect to the stream endpoint after creating a session.
GET /v1/sessions/{session_id}/stream
Authorization: Bearer omk_your_keyEvent types
Session created. Fields: session_id, status, live_view_url, current_url, steps_completed.
Agent completed a step. Fields: session_id, step_number, current_url, evaluation (what happened), memory (what the agent learned), next_goal (what it plans next), actions (planned actions), current_page_title.
Sign-in detected, waiting for manual auth. Fields: session_id, status, live_view_url, pause_reason.
Session resumed after sign-in. Fields: session_id, status, live_view_url.
Structured data extracted. Fields: deliverable_text, current_url, current_page_title, step_number.
File downloaded or screenshot captured. Fields: file_id, file_name, mime_type, size.
Task finished. Fields: session_id, status, steps_completed, deliverable_count, result.
Task failed. Fields: session_id, status, error.
Event format
event: step.completed
data: {"session_id": "abc123", "step_number": 5, "current_url": "https://google.com/search?q=..."}Send a task in plain English. The AI agent navigates the web autonomously, handling CAPTCHAs, sign-ins, file downloads, and structured data extraction.
Send a task in plain English. The AI agent navigates the web autonomously, handling CAPTCHAs, sign-ins, file downloads, and structured data extraction.
Launch an AI-driven browser session with a natural language task
Parameters
task
Requiredstring
Natural language task for the browser agent.
profile
string
Browser profile name for persistent login state and sticky IP.
extract_schema
object
JSON Schema defining the structure of data to extract.
config
object
Session config: model, max_steps (default 50), max_failures (default 5), vision (default true), solve_captchas (default true), pause_on_signin (default true).
agent_context
object
Pre-loaded context: name, skills, accounts (credentials), country (ISO code), additional_instructions.
Example response
{
"success": true,
"data": {
"session_id": "sess_abc123",
"status": "active",
"live_view_url": "https://abc123.anchorbrowser.io/",
"message": "Session created. Agent is navigating."
},
"metadata": {
"request_id": "req_xyz789"
},
"credits_used": 0
}Query your session history. Filter by status (active, finished, failed).
Query your session history. Filter by status (active, finished, failed).
List browser automation sessions with optional filters
Parameters
status
string
Filter by session status: loading, active, paused, finished, failed.
Example response
{
"success": true,
"data": {
"sessions": [
{
"session_id": "sess_abc123",
"status": "finished",
"steps_completed": 8
}
],
"total": 1
},
"credits_used": 0
}Check the current status of a browser session including steps completed, current URL, and live preview link.
Check the current status of a browser session including steps completed, current URL, and live preview link.
Get session status, progress, and live view URL
Parameters
session_id
Requiredstring
The session ID returned from POST /v1/sessions.
Example response
{
"success": true,
"data": {
"session_id": "sess_abc123",
"status": "active",
"live_view_url": "https://abc123.anchorbrowser.io/",
"current_url": "https://google.com",
"steps_completed": 3,
"deliverable_count": 1
},
"credits_used": 0
}Terminate a browser session. The browser is closed and resources are freed.
Terminate a browser session. The browser is closed and resources are freed.
Stop a running browser automation session immediately
Parameters
session_id
Requiredstring
The session ID to stop.
Example response
{
"success": true,
"data": {
"status": "stopped"
},
"credits_used": 0
}Pause the agent for manual intervention (sign-in, verification). The browser stays open. Resume with POST /v1/sessions/{id}/resume.
Pause the agent for manual intervention (sign-in, verification). The browser stays open. Resume with POST /v1/sessions/{id}/resume.
Pause a running session while keeping the browser alive
Parameters
session_id
Requiredstring
The session ID to pause.
Example response
{
"success": true,
"data": {
"status": "paused"
},
"credits_used": 0
}Reconnect to the browser and continue the task from where it paused. The agent picks up with a fresh observation of the current page.
Reconnect to the browser and continue the task from where it paused. The agent picks up with a fresh observation of the current page.
Resume a paused browser session
Parameters
session_id
Requiredstring
The session ID to resume.
Example response
{
"success": true,
"data": {
"session_id": "sess_abc123",
"status": "active",
"live_view_url": "https://abc123.anchorbrowser.io/"
},
"credits_used": 0
}Inject a message into a running session. The agent reads it at the next step and adjusts its approach.
Inject a message into a running session. The agent reads it at the next step and adjusts its approach.
Send a mid-session correction to the running agent
Parameters
session_id
Requiredstring
The session ID to steer.
message
Requiredstring
Correction or guidance for the agent.
Example response
{
"success": true,
"data": {
"status": "steering_message_queued"
},
"credits_used": 0
}Retrieve all deliverables (extracted data, scraped content) produced during the browser session.
Retrieve all deliverables (extracted data, scraped content) produced during the browser session.
Get all structured data extracted during the session
Parameters
session_id
Requiredstring
The session ID.
Example response
{
"success": true,
"data": {
"deliverables": [
{
"deliverable_text": "Extracted 10 profiles from LinkedIn",
"current_url": "https://linkedin.com/search",
"step_number": 5
}
],
"total": 1
},
"credits_used": 0
}Get metadata for all files produced: downloads, screenshots, generated documents.
Get metadata for all files produced: downloads, screenshots, generated documents.
List all files created during the session
Parameters
session_id
Requiredstring
The session ID.
Example response
{
"success": true,
"data": {
"files": [
{
"file_id": "file_abc123",
"file_name": "screenshot.png",
"mime_type": "image/png",
"size": 245000
}
],
"total": 1
},
"credits_used": 0
}Retrieve metadata for a file created during a browser session.
Retrieve metadata for a file created during a browser session.
Get file metadata for a specific file
Parameters
file_id
Requiredstring
The file ID.
Example response
{
"success": true,
"data": {
"file_id": "file_abc123",
"file_name": "report.pdf",
"mime_type": "application/pdf",
"size": 1024000
},
"credits_used": 0
}Create a named browser profile that persists cookies, localStorage, and login state across sessions with a dedicated residential IP.
Create a named browser profile that persists cookies, localStorage, and login state across sessions with a dedicated residential IP.
Create a persistent browser profile with sticky IP
Parameters
name
Requiredstring
Profile name (must be unique per user).
country
string
ISO country code for sticky residential proxy IP.
Example response
{
"success": true,
"data": {
"profile_id": "bb_abc123_linkedin",
"name": "linkedin-account",
"country": "us",
"provider_name": "anchor"
},
"credits_used": 0
}Get all persistent browser profiles associated with your account.
Get all persistent browser profiles associated with your account.
List all browser profiles
Parameters
Example response
{
"success": true,
"data": {
"profiles": [
{
"profile_id": "bb_abc123_linkedin",
"name": "linkedin-account",
"provider_name": "anchor"
}
],
"total": 1
},
"credits_used": 0
}Permanently delete a browser profile. All stored cookies, localStorage, and the dedicated IP are released.
Permanently delete a browser profile. All stored cookies, localStorage, and the dedicated IP are released.
Delete a browser profile and its persistent state
Parameters
profile_id
Requiredstring
The profile ID to delete.
Example response
{
"success": true,
"data": {
"status": "deleted"
},
"credits_used": 0
}