Perplexity WebUI Scraper

Python scraper to extract AI responses from Perplexity's web interface.

Documentation: perplexity-webui-scraper.readthedocs.io

About

This unofficial library uses Perplexity's internal WebUI endpoints with a browser session token. It supports conversations, file uploads, streaming, an MCP server, and an OpenAI-compatible REST API.

A Perplexity account and its browser session token are required. Free accounts support text prompts; paid tiers are required for Pro/Max models and file uploads.

Community

• Contributing guide
• Security policy
• Support guide
• Code of conduct
• Discussions
• Sponsor the project

Installation

Install the package depending on your use case:

This project is distributed as a Python package on PyPI and as optional container images on GHCR. GitHub Releases contain the Python wheel and source distribution; native standalone executables are not published.

Core library

Install the core Python library without optional features.

uv add perplexity-webui-scraper

All optional features

Install the cli, api, and mcp extras together.

uv add "perplexity-webui-scraper[all]"

CLI tools

Install with terminal UX dependencies to use the interactive chat and token CLI commands.

uv add "perplexity-webui-scraper[cli]"

Servers

Install dependencies required for the MCP Server or the OpenAI-compatible REST API.

# MCP Server for AI agents
uv add "perplexity-webui-scraper[mcp]"

# OpenAI-compatible API server
uv add "perplexity-webui-scraper[api]"

Quick Start

1. Get your session token

# Interactive email authentication
uv run perplexity-webui-scraper token

Or retrieve __Secure-next-auth.session-token manually from your browser cookies on perplexity.ai.

2. Basic usage

from perplexity_webui_scraper import Perplexity

client = Perplexity(session_token="YOUR_TOKEN")
conversation = client.create_conversation()

print(client.get_account_profile().account_tier)

conversation.ask("What is quantum computing?")
print(conversation.answer)

# Follow-ups preserve context automatically
conversation.ask("Explain it simpler")
print(conversation.answer)

Before each prompt, the library checks /api/auth/session and raises ModelAccessError if an available model requires a higher tier than the authenticated account. When the session payload does not expose enough subscription data, it falls back to /rest/user/settings. Models use one of three statuses: available (confirmed working normally), unknown (not yet verified, including custom identifiers), or unavailable (confirmed not working). is_official separately records whether a model is listed in Perplexity's official WebUI. last_tested_at records the last test in ISO 8601 UTC and is null for untested models. Any non-available status requires allow_risky_model=True; after acknowledgement, the backend makes the final entitlement decision. Free accounts can use text prompts, but file attachments raise FileAccessError.

perplexity/best adapts to the account tier: free accounts use Perplexity's internal turbo preference, while Pro/Max accounts use pplx_pro_upgraded; both use copilot mode.

3. Streaming

for chunk in conversation.ask("Explain AI", stream=True):
    if chunk.last_chunk:
        print(chunk.last_chunk, end="", flush=True)

4. Choose a model

from perplexity_webui_scraper import ConversationConfig

conversation = client.create_conversation(ConversationConfig(model="perplexity/best"))
conversation.ask("Solve this step by step: ...")
print(conversation.answer)

5. List registered models

from perplexity_webui_scraper import MODELS

for model in MODELS.list_all():
    print(f"{model.id:40} {model.name}")

Available CLI

OpenAI-Compatible API

Run a local server that accepts the supported OpenAI chat-completions fields and forwards requests to Perplexity. Each request passes the Perplexity session token through Authorization: Bearer.

# Start the server (no token needed at startup)
perplexity-webui-scraper api

# Custom host and port
perplexity-webui-scraper api --host 0.0.0.0 --port 8080

# Development mode with auto-reload
perplexity-webui-scraper api --reload

Running via Container (Podman)

# Pull the published multi-arch API image
podman pull ghcr.io/henrique-coder/perplexity-webui-scraper:latest

# Run the server (exposing port 8000)
podman run --rm -p 8000:8000 ghcr.io/henrique-coder/perplexity-webui-scraper:latest

Optional MCP image for containerized stdio setups:

# Pull the published multi-arch MCP image
podman pull ghcr.io/henrique-coder/perplexity-webui-scraper:mcp

# Run MCP server (requires token)
podman run --rm -e PERPLEXITY_SESSION_TOKEN=your_token ghcr.io/henrique-coder/perplexity-webui-scraper:mcp

For local development, you can still build the provided container files:

# API image: installs the `api` extra, exposes port 8000, and starts the REST server.
podman build -t perplexity-api -f Containerfile .
podman run --rm -it -p 8000:8000 perplexity-api

# MCP image: installs the `mcp` extra and starts the stdio MCP server. It does not expose an HTTP port.
podman build -t perplexity-mcp -f Containerfile.mcp .
podman run --rm -it -e PERPLEXITY_SESSION_TOKEN=your_token perplexity-mcp

CLI options

Authentication

Pass your Perplexity session token as the API key in every request:

# curl
export PERPLEXITY_SESSION_TOKEN="your_session_token"
curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "perplexity/best", "messages": [{"role": "user", "content": "Hello!"}]}'

# Streaming
curl -N http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "perplexity/best", "messages": [{"role": "user", "content": "Hello!"}], "stream": true}'

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="YOUR_SESSION_TOKEN",  # sent as Authorization: Bearer automatically
)

response = client.chat.completions.create(
    model="perplexity/best",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

API endpoints

Fields not supported by Perplexity (e.g. temperature, top_p) are accepted for client compatibility but silently ignored.

MCP Server

Expose every Perplexity model as a separate tool for AI agents (Claude Desktop, Antigravity, etc.):

{
  "mcpServers": {
    "perplexity-webui-scraper": {
      "command": "uvx",
      "args": [
        "--from",
        "perplexity-webui-scraper[mcp]@latest",
        "perplexity-webui-scraper",
        "mcp"
      ],
      "env": { "PERPLEXITY_SESSION_TOKEN": "your_token_here" }
    }
  }
}

See the MCP documentation for tools and configuration.

Disclaimer

This is an unofficial library. It uses internal APIs that may change without notice. Use at your own risk. By using this library, you agree to Perplexity AI's Terms of Service.