Maxun Python SDK

The official Python SDK for Maxun — turn any website into an API.

Works with both Maxun Cloud and Maxun Open Source.

What can you do with Maxun SDK?

• Extract structured data from any website
• Scrape entire pages as Markdown or HTML
• Crawl multiple pages automatically to discover and scrape content
• Perform web searches and extract results as metadata or full content
• Use AI to extract data with natural language prompts
• Capture screenshots (visible area or full page)
• Automate workflows with clicks, form fills, and navigation
• Schedule recurring jobs to keep your data fresh
• Get webhooks when extractions complete
• Handle pagination automatically (scroll, click, load more)

Installation

pip install maxun

With LLM support:

pip install "maxun[anthropic]"# Anthropic Claude
pip install "maxun[openai]"# OpenAI GPT
pip install "maxun[all]"# All LLM providers

Local Development

Dependencies are declared in pyproject.toml.

To install the SDK locally in editable mode:

cd python-sdk
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .# core only
pip install -e ".[all]"# core + all LLM providers

Configuration

frommaxunimportConfigconfig=Config(
api_key="your-api-key", # Requiredbase_url="https://app.maxun.dev/api/sdk/", # Optional, defaults to localhostteam_id="your-team-uuid", # Optional, for team-scoped robots
)

Environment variables are supported via a .env file (uses python-dotenv):

MAXUN_API_KEY=your-api-key
MAXUN_BASE_URL=https://app.maxun.dev/api/sdk/
MAXUN_TEAM_ID=your-team-uuid

Core Classes

Scrape

Scrape full pages as Markdown, HTML, or screenshots.

frommaxunimportScrape, Configscraper=Scrape(Config(api_key="..."))
robot=awaitscraper.create(
"Page Scraper",
"https://example.com",
formats=["markdown", "html"],
)
result=awaitrobot.run()
print(result["data"]["markdown"])

Available formats: "markdown", "html", "screenshot-visible", "screenshot-fullpage"

Crawl

Crawl multiple pages starting from a URL.

frommaxunimportCrawl, CrawlConfig, Configcrawler=Crawl(Config(api_key="..."))
robot=awaitcrawler.create(
"Site Crawler",
"https://example.com",
CrawlConfig(
mode="domain", # "domain" | "subdomain" | "path"limit=50,
max_depth=3,
use_sitemap=True,
follow_links=True,
respect_robots=True,
),
)
result=awaitrobot.run()

Search

Search the web and collect results.

frommaxunimportSearch, SearchConfig, Configsearcher=Search(Config(api_key="..."))
robot=awaitsearcher.create(
"AI News Search",
SearchConfig(
query="artificial intelligence 2025",
mode="discover", # "discover" | "scrape"limit=10,
),
)
result=awaitrobot.run()

Extract

Build robots that extract structured data from pages.

frommaxunimportExtract, Configextractor=Extract(Config(api_key="..."))
# Capture specific text fieldsrobot=await (
extractor
.create("My Robot")
.navigate("https://example.com")
.capture_text({"Title": "h1", "Price": ".price"})
)
# Capture a list of items with optional paginationrobot=await (
extractor
.create("Product List")
.navigate("https://shop.example.com")
.capture_list({
"selector": "article.product",
"pagination": {"type": "clickNext", "selector": "a.next"},
"maxItems": 100,
})
)
result=awaitrobot.run()

LLM Extraction

Use a natural language prompt to extract data.

frommaxunimportExtract, Configextractor=Extract(Config(api_key="..."))
robot=awaitextractor.extract(
prompt="Extract the product name, price, and rating",
url="https://shop.example.com/product/123",
llm_provider="anthropic",
llm_model="claude-3-5-sonnet-20241022",
llm_api_key="your-anthropic-key",
)
result=awaitrobot.run()

Robot Management

All robot types return a Robot instance with a consistent API:

# Run the robotresult=awaitrobot.run()
# Schedule recurring runsawaitrobot.schedule({
"runEvery": 1,
"runEveryUnit": "DAYS",
"timezone": "UTC",
})
# Add a webhookawaitrobot.add_webhook({
"url": "https://your-server.com/webhook",
"events": ["run.completed", "run.failed"],
})
# Get execution historyruns=awaitrobot.get_runs()
latest=awaitrobot.get_latest_run()
specific=awaitrobot.get_run("run-id")
# Update metadata or workflowawaitrobot.update({"meta": {"name": "New Name"}})
awaitrobot.refresh() # reload from server# Deleteawaitrobot.delete()

Scheduling

frommaxunimportScheduleConfigawaitrobot.schedule({
"runEvery": 6,
"runEveryUnit": "HOURS", # MINUTES | HOURS | DAYS | WEEKS | MONTHS"timezone": "America/New_York",
})
# Stop schedulingawaitrobot.unschedule()
# Read current scheduleschedule=robot.get_schedule()

Webhooks

awaitrobot.add_webhook({
"url": "https://your-server.com/webhook",
"events": ["run.completed", "run.failed"],
})
webhooks=robot.get_webhooks()
awaitrobot.remove_webhooks()

Error Handling

frommaxunimportMaxunErrortry:
result=awaitrobot.run()
exceptMaxunErrorase:
print(f"Error {e.status_code}: {e}")
print(f"Details: {e.details}")

Types Reference

Type	Description
Config	SDK configuration (api_key, base_url, team_id)
CrawlConfig	Crawl robot configuration
SearchConfig	Search robot configuration
ScheduleConfig	Schedule configuration
WebhookConfig	Webhook configuration
ExtractListConfig	List capture configuration
PaginationConfig	Pagination strategy
MaxunError	SDK exception with status_code and details

Examples

See the examples/ directory for complete working examples.

Requirements

• Python 3.8+
• httpx >= 0.24.0
• python-dotenv >= 1.0.0
• Optional: anthropic >= 0.18.0, openai >= 1.0.0