Python SDK

pip install alterlab

from alterlab import AlterLab

# Initialize the client
client = AlterLab(api_key="sk_live_...")  # or set ALTERLAB_API_KEY env var

# Scrape a webpage
result = client.scrape("https://example.com")

# Access the content
print(result.text)          # Extracted text content
print(result.html)          # Raw HTML
print(result.json)          # Structured JSON (Schema.org, metadata)
print(result.status_code)   # HTTP status code

# Access billing info
print(result.billing.cost_dollars)  # Cost in USD
print(result.billing.tier_used)     # Which tier was used

from alterlab import AlterLab

# Basic initialization
client = AlterLab(api_key="sk_live_...")

# With all options
client = AlterLab(
    api_key="sk_live_...",
    base_url="https://alterlab.io",  # Custom endpoint (optional)
    timeout=120,                      # Request timeout in seconds
    max_retries=3,                    # Auto-retry on transient failures
    retry_delay=1.0                   # Initial retry delay (exponential backoff)
)

# From environment variable
import os
os.environ["ALTERLAB_API_KEY"] = "sk_live_..."
client = AlterLab()  # Reads from ALTERLAB_API_KEY

from alterlab import AlterLab, CostControls

client = AlterLab(api_key="sk_live_...")

# Limit to cheap tiers only
result = client.scrape(
    "https://example.com",
    cost_controls=CostControls(
        max_tier="2",       # Don't go above HTTP tier
        prefer_cost=True,   # Optimize for lowest cost
        fail_fast=True      # Error instead of escalating
    )
)

# Estimate cost before scraping
estimate = client.estimate_cost("https://linkedin.com")
print(f"Estimated: ${estimate.estimated_cost_dollars:.4f}")
print(f"Confidence: {estimate.confidence}")

import asyncio
from alterlab import AsyncAlterLab

async def main():
    async with AsyncAlterLab(api_key="sk_live_...") as client:
        # Single request
        result = await client.scrape("https://example.com")
        print(result.text)

        # Concurrent requests (parallel scraping)
        urls = [
            "https://example.com/page1",
            "https://example.com/page2",
            "https://example.com/page3",
        ]

        results = await asyncio.gather(*[client.scrape(url) for url in urls])

        for r in results:
            print(r.title, r.billing.cost_dollars)

asyncio.run(main())

from alterlab import AlterLab, AdvancedOptions

client = AlterLab(api_key="sk_live_...")

# Use your configured proxy integration
result = client.scrape(
    "https://example.com",
    advanced=AdvancedOptions(
        use_own_proxy=True,
        proxy_country="US"  # Optional: request specific geo
    )
)

# Check if BYOP was applied
if result.billing.byop_applied:
    print(f"Saved {result.billing.byop_discount_percent}%!")

from alterlab import AlterLab

client = AlterLab(api_key="sk_live_...")

# Submit a batch of URLs
batch = client.batch_scrape(
    urls=[
        "https://example.com/page-1",
        "https://example.com/page-2",
        "https://example.com/page-3",
    ],
    formats=["markdown", "json"],
    webhook_url="https://your-server.com/webhook"  # Optional
)

print(f"Batch ID: {batch.batch_id}")
print(f"Status: {batch.status}")  # processing

# Poll for results (blocks until complete)
results = client.get_batch(batch.batch_id, wait=True)
for item in results.items:
    print(f"{item.url}: {item.status}")

from alterlab import AlterLab

client = AlterLab(api_key="sk_live_...")

# Create a daily schedule
schedule = client.create_schedule(
    name="Daily price check",
    urls=["https://store.example.com/product-1"],
    cron="0 9 * * *",       # Every day at 9am
    timezone="America/New_York",
    formats=["json"],
    webhook_url="https://your-server.com/schedule-results"
)

print(f"Schedule ID: {schedule.id}")

# List all schedules
schedules = client.list_schedules()
for s in schedules:
    print(f"{s.name}: {s.cron} ({s.status})")

# Pause/resume
client.pause_schedule(schedule.id)
client.resume_schedule(schedule.id)

# View execution history
history = client.get_schedule_history(schedule.id)
for run in history:
    print(f"{run.executed_at}: {run.status}")

from alterlab import AlterLab

client = AlterLab(api_key="sk_live_...")

# Create a session with cookies
session = client.create_session(
    name="Amazon Login",
    domain="amazon.com",
    cookies={"session-id": "...", "session-token": "..."}
)

# Scrape with stored session
result = client.scrape(
    "https://amazon.com/gp/yourstore",
    session_id=session.id
)

# List sessions
sessions = client.list_sessions()

# Validate session (check if cookies still work)
status = client.validate_session(session.id)
print(f"Valid: {status.is_valid}")

from alterlab import (
    AlterLab,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    ScrapeError,
    TimeoutError
)

client = AlterLab(api_key="sk_live_...")

try:
    result = client.scrape("https://example.com")
    print(result.text)

except AuthenticationError:
    print("Invalid API key")

except InsufficientCreditsError:
    print("Please top up your balance")

except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

except ScrapeError as e:
    print(f"Scraping failed: {e.message}")

except TimeoutError:
    print("Request timed out")