Browser

Overview

The Browser API provides remote browser automation via Chrome DevTools Protocol (CDP). Connect using Playwright, Puppeteer, or any CDP-compatible client to automate web interactions in isolated browser environments.

Browsers auto-terminate after 5 minutes of inactivity.

Authentication

Set your API key as an environment variable:

macOS/Linux
Windows

export PERPLEXITY_API_KEY="your_api_key_here"

setx PERPLEXITY_API_KEY "your_api_key_here"

Quick Start

Create a browser session, connect via CDP, and clean up:

import asyncio
import os
from perplexity import Perplexity
from playwright.async_api import async_playwright

client = Perplexity()

# Create browser session
# Note: Use extra_body={} to ensure empty JSON body is sent
session = client.browser.sessions.create(extra_body={})
print(f"Session ID: {session.session_id}")

# Connect via CDP
async def browse():
    ws_url = f"wss://api.perplexity.ai/v1/browser/proxy/sessions/{session.session_id}/websocket?token={client.api_key}"

    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(ws_url)
        page = await browser.new_page()
        await page.goto("https://example.com")
        print(await page.title())
        await browser.close()

asyncio.run(browse())

# Cleanup
client.browser.sessions.delete(session_id=session.session_id)

import asyncio
import requests
import os
from playwright.async_api import async_playwright

API_KEY = os.getenv("PERPLEXITY_API_KEY")

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

# Create browser session
session = requests.post(
    "https://api.perplexity.ai/v1/browser/sessions",
    json={},
    headers=headers
).json()
session_id = session["session_id"]
print(f"Session ID: {session_id}")

# Connect via CDP
async def browse():
    ws_url = f"wss://api.perplexity.ai/v1/browser/proxy/sessions/{session_id}/websocket?token={API_KEY}"

    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(ws_url)
        page = await browser.new_page()
        await page.goto("https://example.com")
        print(await page.title())
        await browser.close()

asyncio.run(browse())

# Cleanup
requests.delete(
    f"https://api.perplexity.ai/v1/browser/sessions/{session_id}",
    headers=headers
)

# Create browser session
SESSION=$(curl -s -X POST \
  "https://api.perplexity.ai/v1/browser/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -d '{}')
SID=$(echo $SESSION | jq -r '.session_id')
echo "Session ID: $SID"

# WebSocket URL for CDP connection:
# wss://api.perplexity.ai/v1/browser/proxy/sessions/$SID/websocket?token=$PERPLEXITY_API_KEY

# Cleanup
curl -s -X DELETE \
  "https://api.perplexity.ai/v1/browser/sessions/$SID" \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY"

Response

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running"
}

Endpoints

Method	Endpoint	Description
POST	`/v1/browser/sessions`	Create browser session
DELETE	`/v1/browser/sessions/{id}`	Stop browser session

WebSocket Connection (CDP)

Connect to the browser via Chrome DevTools Protocol:

wss://api.perplexity.ai/v1/browser/proxy/sessions/{session_id}/websocket?token=<YOUR_TOKEN>

The WebSocket URL uses token as a query parameter for authentication, not the Authorization header.

Examples

Once connected via CDP, you have full browser automation capabilities. Here are common operations:

Take a Screenshot

# Save screenshot to file
await page.screenshot(path="screenshot.png")

# Get screenshot as bytes
screenshot_bytes = await page.screenshot()

# Full page screenshot (scrolls entire page)
await page.screenshot(path="fullpage.png", full_page=True)

Navigate and Get Page Info

# Navigate to URL
await page.goto("https://example.com")

# Get current page info
title = await page.title()
url = page.url
content = await page.content()

print(f"Title: {title}")
print(f"URL: {url}")
print(f"Content length: {len(content)} characters")

Execute JavaScript

# Run JavaScript and get result
result = await page.evaluate("document.title")

# Evaluate expressions
count = await page.evaluate("document.querySelectorAll('a').length")
print(f"Found {count} links on page")

# Modify the page
await page.evaluate("document.body.style.backgroundColor = 'lightblue'")

# Go back to previous page
await page.go_back()

# Go forward
await page.go_forward()

# Reload current page
await page.reload()

# Wait for navigation
await page.goto("https://example.com", wait_until="networkidle")

Extract Page Content

# Get all visible text
text = await page.inner_text("body")

# Get specific element text
heading = await page.inner_text("h1")

# Get element attribute
href = await page.get_attribute("a.main-link", "href")

# Query multiple elements
links = await page.query_selector_all("a")
for link in links:
    print(await link.get_attribute("href"))

Interact with Elements

# Click a button
await page.click("button#submit")

# Fill a form field
await page.fill("input[name='search']", "perplexity")

# Press keyboard keys
await page.press("input[name='search']", "Enter")

# Select dropdown option
await page.select_option("select#country", "US")

For more Playwright operations, see the Playwright documentation.

Rate Limits

Limit	Value
Browsers created per minute	5
Concurrent browsers	10
Requests per second (other APIs)	1
Inactivity timeout	5 minutes

Always delete browser sessions when done. Sessions count toward your concurrent limit (10) and will block new session creation if the limit is reached. Sessions auto-terminate after 5 minutes of inactivity, but manual cleanup is recommended.

Pricing

Browser sessions are billed based on compute time usage.

Price per Hour	Minimum Billing
$0.25	Rounded up to nearest minute

Usage Calculation: Billing is calculated based on the total time your browser session is active, rounded up to the nearest minute. For example, a session running for 1 minute and 15 seconds will be billed for 2 minutes ($0.0083).See detailed pricing information and cost examples for all Perplexity APIs on our Pricing page.

Contact Sales

Get in touch with our team to discuss enterprise pricing and custom requirements.

Error Codes

Code	Meaning
400	Invalid request
404	Session not found
429	Rate limit exceeded
500	Internal error

Next Steps

Browser API Reference

Complete API documentation for browser endpoints.

Getting Started

Perplexity SDK

Agent API

Search API

Sonar API

Browser API

Embeddings API

Admin & Management

Resources

Overview

Authentication

Quick Start

Endpoints

WebSocket Connection (CDP)

Examples

Take a Screenshot

Navigate and Get Page Info

Execute JavaScript

Navigation Controls

Extract Page Content

Interact with Elements

Rate Limits

Pricing

Contact Sales

Error Codes

Next Steps

Browser API Reference

​Overview

​Authentication

​Quick Start

​Endpoints

​WebSocket Connection (CDP)

​Examples

​Take a Screenshot

​Navigate and Get Page Info

​Execute JavaScript

​Navigation Controls

​Extract Page Content

​Interact with Elements

​Rate Limits

​Pricing

Contact Sales

​Error Codes

​Next Steps

Browser API Reference

Overview

Authentication

Quick Start

Endpoints

WebSocket Connection (CDP)

Examples

Take a Screenshot

Navigate and Get Page Info

Execute JavaScript

Navigation Controls

Extract Page Content

Interact with Elements

Rate Limits

Pricing

Error Codes

Next Steps