### Quick Start

Source: https://alterlab.io/docs/sdk/node

A quick guide to get started with the AlterLab Node.js SDK, including client initialization and basic website scraping.

```APIDOC
## Quick Start

Initialize the client with your API key and start scraping websites.

### TypeScript Example

```typescript
import { AlterLab } from 'alterlab';

// Initialize client
const client = new AlterLab({ apiKey: 'sk_live_...' });

// Scrape a website
const result = await client.scrape('https://example.com');

console.log(result.text);                  // Extracted text
console.log(result.json);                  // Structured JSON
console.log(result.billing.costDollars);   // Cost in USD
console.log(result.billing.tierUsed);      // Which tier succeeded
```

### JavaScript Example

```javascript
import { AlterLab } from 'alterlab';

// Initialize client
const client = new AlterLab({ apiKey: 'sk_live_...' });

// Scrape a website
const result = await client.scrape('https://example.com');

console.log(result.text);                  // Extracted text
console.log(result.json);                  // Structured JSON
console.log(result.billing.costDollars);   // Cost in USD
console.log(result.billing.tierUsed);      // Which tier succeeded
```
```

--------------------------------

### Install AlterLab SDK

Source: https://alterlab.io/docs/migrations/apify

Commands to remove the Apify client and install the AlterLab SDK.

```bash
# Remove Apify
pip uninstall apify-client

# Install AlterLab
pip install alterlab
# or: npm install @alterlab/sdk
```

--------------------------------

### Install AlterLab SDK

Source: https://alterlab.io/docs/sdk/python

Install the package using pip.

```bash
pip install alterlab
```

--------------------------------

### Install AlterLab SDK

Source: https://alterlab.io/docs/tutorials/authenticated-amazon

Install the required SDK for Python or Node.js environments.

```bash
# Install the SDK
pip install alterlab
# or
npm install @alterlab/sdk
```

--------------------------------

### Installation

Source: https://alterlab.io/docs/sdk/python

Install the AlterLab Python SDK using pip.

```APIDOC
## Installation

```bash
pip install alterlab
```
```

--------------------------------

### Install AlterLab SDK

Source: https://alterlab.io/docs/sdk

Installation commands for Python package managers.

```bash
# Using pip
pip install alterlab

# Using poetry
poetry add alterlab

# Using pipenv
pipenv install alterlab
```

--------------------------------

### Installation

Source: https://alterlab.io/docs/sdk/node

Install the AlterLab Node.js SDK using npm, yarn, or pnpm.

```APIDOC
## Installation

Install the AlterLab Node.js SDK using your preferred package manager:

### npm
```bash
npm install @alterlab/sdk
```

### yarn
```bash
yarn add @alterlab/sdk
```

### pnpm
```bash
pnpm add @alterlab/sdk
```
```

--------------------------------

### MCP Server Installation

Source: https://alterlab.io/docs/integrations/mcp

Instructions for installing the AlterLab MCP server globally or using npx.

```APIDOC
## MCP Server Installation

### Global Install (Recommended for Frequent Use)

```bash
npm install -g alterlab-mcp-server
```

### On-Demand via npx (No Install Needed)

```bash
npx -y alterlab-mcp-server
```

**Note:** Node.js 18 or later is required.
```

--------------------------------

### Install AlterLab Node.js SDK

Source: https://alterlab.io/docs/sdk/node

Install the AlterLab Node.js SDK using npm. Ensure you have Node.js 18+.

```bash
npm install @alterlab/sdk
```

--------------------------------

### Quick Start

Source: https://alterlab.io/docs/sdk/python

Initialize the AlterLab client and perform a basic web scrape.

```APIDOC
## Quick Start

```python
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
```
```

--------------------------------

### AlterLab Response Format Example

Source: https://alterlab.io/docs/migrations/firecrawl

Example JSON response from the AlterLab compatibility endpoint, including data and AlterLab-specific metadata.

```JSON
{
  "success": true,
  "data": {
    "markdown": "# Example Domain\n\nThis domain is for use...",
    "html": "<h1>Example Domain</h1><p>This domain is for use...</p>",
    "rawHtml": "<!doctype html><html>...</html>",
    "links": [
      "https://iana.org/domains/example"
    ],
    "metadata": {
      "title": "Example Domain",
      "description": "Example description",
      "sourceURL": "https://example.com/",
      "statusCode": 200
    }
  },
  "alterlab": {
    "tier_used": "1",
    "credits": 1,
    "response_time_ms": 842,
    "cached": false
  }
}
```

--------------------------------

### Alerts API - Full Example

Source: https://alterlab.io/docs/guides/alerts

A comprehensive Python example demonstrating various operations on the Alerts API, including creating rules, listing rules, checking history, and disabling rules.

```APIDOC
## Python Example - Alerts API

### Description
This example demonstrates how to use the AlterLab API with Python's `requests` library to manage alerts. It covers creating different types of alert rules, listing existing rules, retrieving alert history, and disabling a rule.

### Code Example
```python
import requests

API_URL = "https://api.alterlab.io/api/v1"
HEADERS = {
    "Authorization": "Bearer your_jwt_token",
    "Content-Type": "application/json",
}

# Create a credit threshold alert
try:
    rule = requests.post(
        f"{API_URL}/alerts/rules",
        headers=HEADERS,
        json={
            "name": "Low credit warning",
            "alert_type": "credit_threshold",
            "conditions": {"threshold_percent": 20},
            "channels": {"email": True},
            "cooldown_minutes": 30,
        },
    ).json()
    print(f"Alert rule created: {rule['id']}")
    print(f"Type: {rule['alert_type']}, Active: {rule['is_active']}")

    # Create a failure rate alert for specific domains
    failure_rule = requests.post(
        f"{API_URL}/alerts/rules",
        headers=HEADERS,
        json={
            "name": "E-commerce failure spike",
            "alert_type": "domain_failure_rate",
            "conditions": {
                "threshold": 40,
                "window_minutes": 30,
                "min_requests": 10,
            },
            "domain_filter": ["amazon.com", "ebay.com", "walmart.com"],
            "channels": {"email": True, "webhook_id": "wh_abc123"},
            "cooldown_minutes": 60,
        },
    ).json()
    print(f"Failure alert created: {failure_rule['id']}")

    # List all active rules
    rules = requests.get(
        f"{API_URL}/alerts/rules",
        headers=HEADERS,
    ).json()

    print("\nListing active rules:")
    for r in rules["rules"]:
        status = "active" if r["is_active"] else "disabled"
        print(f"  {r['name']} ({r['alert_type']}) — {status}")

    # Check alert history
    history = requests.get(
        f"{API_URL}/alerts/history?limit=10",
        headers=HEADERS,
    ).json()

    print(f"\nRecent alerts ({history['total']} total):")
    for alert in history["alerts"]:
        print(f"  [{alert['created_at']}] {alert['alert_type']}: {alert['message']}")

    # Disable a rule
    disable_response = requests.patch(
        f"{API_URL}/alerts/rules/{rule['id']}",
        headers=HEADERS,
        json={"is_active": False},
    )
    if disable_response.status_code == 200:
        print(f"\nRule {rule['id']} disabled successfully.")
    else:
        print(f"\nFailed to disable rule {rule['id']}. Status code: {disable_response.status_code}")

except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
except KeyError as e:
    print(f"Missing key in response: {e}")

```
```

--------------------------------

### Install MCP Server Globally

Source: https://alterlab.io/docs/integrations/mcp

Install the MCP server globally for frequent use. Node.js 18 or later is required.

```bash
npm install -g alterlab-mcp-server
```

--------------------------------

### Start a Crawl

Source: https://alterlab.io/docs/guides/crawling

Submit a start URL to discover and scrape an entire website. This endpoint returns an 'Accepted' status with a crawl ID for subsequent polling.

```APIDOC
## POST /api/v1/crawl

### Description
Submit a start URL to discover and scrape an entire website. Returns 202 Accepted with a crawl ID for polling.

### Method
POST

### Endpoint
/api/v1/crawl

### Parameters
#### Request Body
- **url** (string) - Required - Start URL for the crawl (http/https)
- **max_pages** (integer) - Optional - Maximum number of pages to scrape (1--100,000), defaults to 50
- **max_depth** (integer) - Optional - Maximum link-following depth from start URL (0 = start page only, max 50), defaults to 3
- **include_patterns** (string[]) - Optional - Glob patterns -- only scrape URLs whose path matches at least one
- **exclude_patterns** (string[]) - Optional - Glob patterns -- skip URLs whose path matches any
- **formats** (string[]) - Optional - Output formats per page: text, json, json_v2, html, markdown
- **extraction_schema** (object) - Optional - JSON schema for structured extraction on each page
- **extraction_profile** (string) - Optional - Pre-defined profile: auto, product, article, job_posting, faq, recipe, event
- **webhook_url** (string) - Optional - URL to receive a crawl.completed webhook when all pages finish
- **respect_robots** (boolean) - Optional - Respect robots.txt rules for the target domain, defaults to true
- **include_subdomains** (boolean) - Optional - Include links to subdomains during discovery, defaults to false
- **advanced** (object) - Optional - Advanced scraping options applied to every page
- **cost_controls** (object) - Optional - Cost controls for the entire crawl

### Advanced Options (within `advanced` object)
- **render_js** (boolean) - Optional - Render JavaScript on every page (forces Tier 4), defaults to false
- **screenshot** (boolean) - Optional - Capture a screenshot of every crawled page, defaults to false
- **use_proxy** (boolean) - Optional - Route all crawl requests through premium proxy, defaults to false
- **wait_for** (null) - Optional - CSS selector to wait for on each page before extracting
- **timeout** (integer) - Optional - Timeout per page in seconds (1--300), defaults to 90

### Cost Controls (within `cost_controls` object)
- **max_credits** (integer) - Optional - Maximum total cost to spend on this crawl
- **max_tier** (integer) - Optional - Maximum tier to use for page scrapes (1, 2, 3, 3.5, or 4)
- **force_tier** (integer) - Optional - Force a specific tier for all pages (1, 2, 3, 3.5, or 4)

### Request Example
```json
{
  "url": "https://example.com",
  "max_pages": 100,
  "max_depth": 3,
  "include_patterns": ["/blog/*", "/docs/*"],
  "exclude_patterns": ["/admin/*", "*.pdf"],
  "formats": ["text", "markdown"],
  "webhook_url": "https://your-server.com/webhook"
}
```

### Response
#### Success Response (202 Accepted)
- **crawl_id** (string) - Unique identifier for the crawl
- **status** (string) - Current status of the crawl (e.g., "discovering")
- **estimated_pages** (integer) - Estimated number of pages to be scraped
- **total_enqueued** (integer) - Total number of pages enqueued for scraping
- **estimated_credits** (integer) - Estimated credits required for the crawl
- **message** (string) - Informational message about the crawl status

#### Response Example
```json
{
  "crawl_id": "c9a1b2d3-4e5f-6789-abcd-ef0123456789",
  "status": "discovering",
  "estimated_pages": 47,
  "total_enqueued": 47,
  "estimated_credits": 47000,
  "message": "Crawl started. Poll GET /v1/crawl/{crawl_id} for progress."
}
```
```

--------------------------------

### Authentication Request Examples

Source: https://alterlab.io/docs/migrations/scrapingbee

Comparison of authentication methods between ScrapingBee, ScraperAPI, and AlterLab.

```bash
GET https://app.scrapingbee.com/api/v1/
  ?api_key=YOUR_KEY
  &url=https://example.com
```

```bash
GET http://api.scraperapi.com/
  ?api_key=YOUR_KEY
  &url=https://example.com
```

```bash
POST https://api.alterlab.io/api/v1/scrape
  -H "X-API-Key: sk_live_xxx"
  -d '{"url": "https://example.com"}'
```

--------------------------------

### Start a Web Crawl

Source: https://alterlab.io/docs/guides/crawling

Submit a start URL to discover and scrape an entire website. This request returns a crawl ID for polling progress. Configure include/exclude patterns, desired formats, and a webhook URL for completion notifications.

```bash
curl -X POST https://api.alterlab.io/api/v1/crawl \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "max_pages": 100,
    "max_depth": 3,
    "include_patterns": ["/blog/*", "/docs/*"],
    "exclude_patterns": ["/admin/*", "*.pdf"],
    "formats": ["text", "markdown"],
    "webhook_url": "https://your-server.com/webhook"
  }'
```

--------------------------------

### Connection Test Response

Source: https://alterlab.io/docs/guides/cloud-storage

Example response after testing a storage connection.

```json
{
  "success": true,
  "message": "Connection test passed",
  "error": null
}
```

--------------------------------

### Organization Creation Response

Source: https://alterlab.io/docs/guides/organizations

Example JSON response returned after successfully creating an organization.

```JSON
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Scraping Team",
  "slug": "acme-scraping-team-a1b2c3d4",
  "description": "Our production scraping infrastructure",
  "is_personal": false,
  "role": "owner",
  "member_count": 1,
  "created_at": "2026-03-24T10:00:00Z"
}
```

--------------------------------

### Async Jobs

Source: https://alterlab.io/docs/sdk/node

Guide to performing asynchronous scraping tasks, including starting jobs, checking their status, and waiting for completion.

```APIDOC
## Async Jobs

Handle long-running scraping tasks asynchronously using `scrapeAsync` and related methods.

### Start an Async Job

Initiate a scrape job that returns immediately with a job ID.

```typescript
const jobId = await client.scrapeAsync('https://example.com', {
  mode: 'js',
  advanced: { screenshot: true }
});
console.log(`Job started: ${jobId}`);
```

### Check Job Status

Manually poll for the status and progress of an async job.

```typescript
const status = await client.getJobStatus(jobId);
console.log(`Status: ${status.status}`);
console.log(`Progress: ${status.progress}%`);
```

### Wait for Job Completion

Block execution until the async job completes, with options for polling interval and timeout.

```typescript
const result = await client.waitForJob(jobId, {
  pollInterval: 2000,  // Check every 2 seconds
  timeout: 300000      // 5 minute timeout
});
console.log(result.text);
```
```

--------------------------------

### Full Pipeline: Create Monitors and Register Webhook (Python)

Source: https://alterlab.io/docs/tutorials/monitoring-dashboard

An end-to-end example demonstrating the creation of multiple monitors with different configurations and the registration of a webhook for receiving change notifications.

```python

"""
Complete monitoring dashboard pipeline.
Creates monitors, registers webhooks, and builds a dashboard.
"""
import requests
from datetime import datetime

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.alterlab.io/api/v1"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
WEBHOOK_URL = "https://your-app.com/webhooks/monitor"

# --- 1. Create monitors ---
monitors_config = [
    {
        "name": "Competitor A - Pricing",
        "url": "https://competitor-a.com/pricing",
        "diff_mode": "semantic",
        "cron": "0 */6 * * *",
    },
    {
        "name": "Competitor B - Product",
        "url": "https://competitor-b.com/product/widget",
        "diff_mode": "selector",
        "css_selector": ".price, .stock-status",
        "cron": "0 */2 * * *",
    },
    {
        "name": "Regulatory Page",
        "url": "https://regulator.gov/filings/latest",
        "diff_mode": "semantic",
        "cron": "0 9 * * 1-5",
    },
]

monitor_ids = []
for config in monitors_config:
    payload = {**config, "notify_on": ["change", "error"]}
    resp = requests.post(
        f"{BASE_URL}/monitors", headers=HEADERS, json=payload
    ).json()
    monitor_ids.append(resp["id"])
    print(f"Created monitor: {resp['id']} -> {config['name']}")

# --- 2. Register webhook ---
webhook = requests.post(
    f"{BASE_URL}/webhooks",
    headers=HEADERS,
    json={
        "url": WEBHOOK_URL,
        "events": ["monitor.change_detected", "monitor.error"],
        "description": "Monitoring dashboard",
    },
).json()
print(f"Webhook registered: {webhook['id']}")

```

--------------------------------

### Get Usage Data for Specific Date Range

Source: https://alterlab.io/docs/api/rest

Use this cURL command to retrieve usage statistics within a defined start and end date. Ensure your API key is correctly formatted.

```bash
curl -X GET "https://api.alterlab.io/api/v1/usage?start_date=2025-11-01&end_date=2025-11-30" \
  -H "X-API-Key: sk_live_..."
```

--------------------------------

### Quick Start with Python SDK

Source: https://alterlab.io/docs/sdk

Initialize the client and perform basic scraping tasks including text extraction, JSON parsing, and JavaScript rendering.

```python
from alterlab import AlterLab

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

# Scrape a website
result = client.scrape("https://example.com")
print(result.text)                    # Extracted text
print(result.json)                    # Structured JSON
print(result.billing.cost_dollars)    # Cost breakdown

# With JavaScript rendering
result = client.scrape_js("https://spa-app.com", screenshot=True)
print(result.screenshot_url)
```

--------------------------------

### Node.js: Interact with AlterLab.io API

Source: https://alterlab.io/docs/guides/monitors

This snippet shows how to use the fetch API in Node.js to interact with the AlterLab.io API. It includes examples for creating a monitor, listing monitors, getting recent changes, and browsing snapshot history. Ensure you replace 'your_jwt_token' with a valid JWT.

```typescript
const API_URL = "https://api.alterlab.io/api/v1";
const headers = {
  Authorization: "Bearer your_jwt_token",
  "Content-Type": "application/json",
};

// Create a monitor with CSS selector tracking
const monitor = await fetch(`${API_URL}/monitors`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Competitor pricing tracker",
    url: "https://competitor.com/pricing",
    diff_mode: "selector",
    monitor_selectors: [".price-card", ".plan-name"],
    check_interval: "0 */6 * * *",
    notify_on: "change",
    webhook_url: "https://your-server.com/price-alerts",
  }),
}).then((r) => r.json());

console.log(`Monitor: ${monitor.id}, next check: ${monitor.next_run_at}`);

// List active monitors
const list = await fetch(`${API_URL}/monitors?active_only=true`, {
  headers,
}).then((r) => r.json());

for (const m of list.monitors) {
  console.log(`  ${m.name} — ${m.diff_mode}, ${m.run_count} runs`);
}

// Get recent changes
const changes = await fetch(
  `${API_URL}/monitors/${monitor.id}/diffs`,
  { headers }
).then((r) => r.json());

for (const c of changes.changes) {
  console.log(`  [${c.created_at}] ${c.change_type}`);
}

// Browse snapshot history
const snapshots = await fetch(
  `${API_URL}/monitors/${monitor.id}/snapshots?limit=5`,
  { headers }
).then((r) => r.json());

for (const s of snapshots.snapshots) {
  console.log(`  Snapshot ${s.id.slice(0, 8)}... hash=${s.content_hash.slice(0, 12)}`);
}

```

--------------------------------

### Quick Start with AlterLab

Source: https://alterlab.io/docs/sdk/python

Initialize the client and perform a basic scrape to retrieve text, HTML, JSON, and billing information.

```python
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
```

--------------------------------

### Python API Interaction Example

Source: https://alterlab.io/docs/guides/monitors

Demonstrates creating a monitor, listing active monitors, checking recent changes, and retrieving snapshot history using the Alterlab API.

```python
import requests

API_URL = "https://api.alterlab.io/api/v1"
HEADERS = {
    "Authorization": "Bearer your_jwt_token",
    "Content-Type": "application/json",
}

# Create a price monitoring watch
monitor = requests.post(
    f"{API_URL}/monitors",
    headers=HEADERS,
    json={
        "name": "Competitor pricing tracker",
        "url": "https://competitor.com/pricing",
        "diff_mode": "selector",
        "monitor_selectors": [".price-card", ".plan-name"],
        "check_interval": "0 */6 * * *",
        "notify_on": "change",
        "webhook_url": "https://your-server.com/price-alerts",
    },
).json()

print(f"Monitor created: {monitor['id']}")
print(f"Next check: {monitor['next_run_at']}")

# List active monitors
monitors = requests.get(
    f"{API_URL}/monitors?active_only=true",
    headers=HEADERS,
).json()

for m in monitors["monitors"]:
    print(f"  {m['name']} — mode: {m['diff_mode']}, runs: {m['run_count']}")

# Check recent changes
changes = requests.get(
    f"{API_URL}/monitors/{monitor['id']}/diffs",
    headers=HEADERS,
).json()

for c in changes["changes"]:
    print(f"  [{c['created_at']}] {c['change_type']}")
    if "summary" in c["diff"]:
        print(f"    Summary: {c['diff']['summary']}")

# Get snapshot history
snapshots = requests.get(
    f"{API_URL}/monitors/{monitor['id']}/snapshots?limit=5",
    headers=HEADERS,
).json()

for s in snapshots["snapshots"]:
    print(f"  Snapshot {s['id'][:8]}... hash={s['content_hash'][:12]}")
```

--------------------------------

### Initialize AlterLab Client

Source: https://alterlab.io/docs/sdk/python

Configure the client with custom options or environment variables.

```python
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
```

--------------------------------

### Full Pipeline Setup Script

Source: https://alterlab.io/docs/tutorials/price-monitoring

A complete script to define a price extraction schema, register a webhook, and create daily scraping schedules for multiple products.

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.alterlab.io/api/v1"
WEBHOOK_URL = "https://your-app.com/webhooks/price-update"

# --- 1. Price extraction schema ---
price_schema = {
    "type": "object",
    "properties": {
        "product_name": {"type": "string", "description": "Full product name"},
        "current_price": {"type": "number", "description": "Current selling price"},
        "original_price": {"type": "number", "description": "Original price before discount"},
        "currency": {"type": "string", "description": "Currency code"},
        "in_stock": {"type": "boolean", "description": "Currently in stock"},
        "on_sale": {"type": "boolean", "description": "Discount is active"},
        "seller": {"type": "string", "description": "Seller name"}
    }
}

# --- 2. Register webhook ---
webhook = requests.post(
    f"{BASE_URL}/webhooks",
    headers={"X-API-Key": API_KEY},
    json={
        "url": WEBHOOK_URL,
        "events": ["scrape.completed", "scrape.failed"],
        "description": "Price monitoring pipeline"
    }
).json()
print(f"Webhook registered: {webhook['id']}")
print(f"Save this secret for verification: {webhook['secret']}")

# --- 3. Create schedules for each product ---
products = [
    {"name": "Widget Pro - Store A", "url": "https://store-a.com/widget-pro"},
    {"name": "Widget Pro - Store B", "url": "https://store-b.com/widget-pro"},
    {"name": "Widget Pro - Store C", "url": "https://store-c.com/widget-pro"},
]

schedule_ids = []
for product in products:
    schedule = requests.post(
        f"{BASE_URL}/schedules",
        headers={"X-API-Key": API_KEY},
        json={
            "name": f"Price: {product['name']}",
            "url": product["url"],
            "cron": "0 9 * * *",
            "scrape_options": {
                "extraction_schema": price_schema,
                "extraction_prompt": "Extract current product pricing information.",
                "cache": False
            },
            "webhook_url": WEBHOOK_URL,
            "max_credits_per_execution": 5
        }
    ).json()
    schedule_ids.append(schedule["id"])
    print(f"Schedule created: {schedule['id']} -> {product['name']}")

print(f"\nPipeline ready! {len(schedule_ids)} products monitored daily at 9 AM UTC.")
print(f"Results delivered to: {WEBHOOK_URL}")
```

--------------------------------

### List API Keys Request Example

Source: https://alterlab.io/docs/api/keys

Use this Bash command to list all active API keys for your account. It requires a session token for authentication.

```bash
curl -X GET https://api.alterlab.io/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
```

--------------------------------

### Create a Monitor

Source: https://alterlab.io/docs/guides/monitors

Use this endpoint to define a new monitor. Specify the URL, diff mode, check interval, and notification settings. Optional parameters include timezone and webhook URL.

```bash
curl -X POST https://api.alterlab.io/api/v1/monitors \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{ \
    "name": "Competitor pricing page", \
    "url": "https://competitor.com/pricing", \
    "diff_mode": "semantic", \
    "check_interval": "0 */6 * * *", \
    "timezone": "America/New_York", \
    "notify_on": "change", \
    "webhook_url": "https://your-server.com/monitor-webhook", \
    "options": { \
      "wait_for": ".pricing-table", \
      "timeout": 30 \
    } \
  }'
```

--------------------------------

### Install n8n-nodes-alterlab via CLI

Source: https://alterlab.io/docs/integrations/n8n

Use this command to install the community node directly into your n8n environment via npm.

```bash
npm install n8n-nodes-alterlab

# Restart n8n after installation
n8n start
```

--------------------------------

### GET /api/v1/proxies/{integration_id}/usage

Source: https://alterlab.io/docs/guides/bring-your-own-proxy

Get usage statistics from the proxy provider's API (bandwidth, requests, balance).

```APIDOC
## GET /api/v1/proxies/{integration_id}/usage

### Description
Get usage statistics from the proxy provider's API (bandwidth, requests, balance).

### Method
GET

### Endpoint
/api/v1/proxies/{integration_id}/usage

### Parameters
#### Path Parameters
- **integration_id** (uuid) - Required - Integration ID

### Response
#### Success Response (200)
- **bandwidth_used_gb** (number) - Bandwidth used in GB
- **requests_made** (integer) - Total requests made
- **balance_remaining** (number) - Remaining balance

#### Response Example
{
  "bandwidth_used_gb": 5.0,
  "requests_made": 12500,
  "balance_remaining": 95.50
}
```

--------------------------------

### Perform Initial Scrape Request

Source: https://alterlab.io/docs/api/rest

Demonstrates how to initiate a scrape request using cURL, the requests library, or the official Python SDK.

```Bash
# Using cURL
curl -X POST https://api.alterlab.io/api/v1/scrape \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

```Python
# Using Python
import requests

response = requests.post(
    "https://api.alterlab.io/api/v1/scrape",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"url": "https://example.com"}
)
print(response.json())
```

```Python
# Using Python SDK (Recommended)
from alterlab import AlterLabSync

client = AlterLabSync(api_key="YOUR_API_KEY")
result = client.scrape("https://example.com")
print(result["content"][:100])  # First 100 chars
```

--------------------------------

### Example Markdown Response

Source: https://alterlab.io/docs/guides/output-formats

An example of the JSON response when requesting content in Markdown format. It includes the scraped content with Markdown formatting.

```json
{
  "content": {
    "markdown": "# How to Build a Web Scraper in Python\n\nWeb scraping is the process of extracting data from websites.\n\n## Step 1: Install Dependencies\n\nFirst, install the required packages:\n\n```bash\npip install requests beautifulsoup4\n```\n\n## Step 2: Fetch the Page\n\n| Library | Async | Speed |\n|---------|-------|-------|\n| requests | No | Fast |\n| httpx | Yes | Faster |\n\n> **Tip**: Use httpx for async scraping workloads."
  }
}
```

--------------------------------

### Example RAG Response

Source: https://alterlab.io/docs/guides/output-formats

An example of the JSON response when requesting content in RAG format. It includes metadata about the scraped content and an array of structured chunks.

```json
{
  "content": {
    "rag": {
      "metadata": {
        "title": "How to Build a Web Scraper in Python",
        "description": "A complete guide to building production web scrapers",
        "author": "Jane Doe",
        "published_at": "2026-01-15T10:00:00Z",
        "language": "en",
        "url": "https://example.com/blog/post",
        "domain": "example.com",
        "content_type": "Article",
        "content_type_confidence": 0.95,
        "total_tokens": 1847,
        "total_chunks": 5,
        "word_count": 1420
      },
      "chunks": [
        {
          "index": 0,
          "heading": "How to Build a Web Scraper in Python",
          "heading_level": 1,
          "content": "# How to Build a Web Scraper in Python\n\nWeb scraping is the process of extracting data from websites. In this guide...",
          "token_count": 387,
          "links": [
            { "text": "BeautifulSoup docs", "url": "https://..." }
          ]
        },
        {
          "index": 1,
          "heading": "Install Dependencies",
          "heading_level": 2,
          "content": "## Install Dependencies\n\nFirst, install the required packages:\n\n```bash\npip install requests beautifulsoup4\n```",
          "token_count": 142,
          "links": []
        }
      ]
    }
  }
}
```

--------------------------------

### AlterLab Scrape Request Example

Source: https://alterlab.io/docs/migrations/firecrawl

Example cURL request to the AlterLab scrape endpoint, demonstrating various parameters like formats, waitFor, and timeout.

```Bash
curl -X POST https://api.alterlab.io/api/v0/scrape \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown", "html"],
    "waitFor": 1000,
    "timeout": 30000
  }'
```

--------------------------------

### Verify AlterLab Installation

Source: https://alterlab.io/docs/quickstart/installation

Initialize the client and perform a test scrape request to verify connectivity.

```javascript
import { AlterLab } from '@alterlab/sdk'

const client = new AlterLab({
  apiKey: 'your-api-key'
})

const response = await client.scrape({
  url: 'https://example.com'
})

console.log(response.data)
```

--------------------------------

### Start a Crawl with Python SDK

Source: https://alterlab.io/docs/guides/crawling

Initialize a crawl using the AlterLab Python client with specific configuration parameters.

```Python
import alterlab
import time

client = alterlab.AlterLab(api_key="your_api_key")

# Start a crawl
crawl = client.crawl(
    url="https://example.com",
    max_pages=100,
    max_depth=3,
    include_patterns=["/blog/*", "/docs/*"],
    exclude_patterns=["/admin/*"],
    formats=["text", "markdown"],
    webhook_url="https://your-server.com/webhook",
)

print(f"Crawl ID: {crawl['crawl_id']}")
print(f"Pages discovered: {crawl['estimated_pages']}")
print(f"Estimated credits: {crawl['estimated_credits']}")
```

--------------------------------

### Example json_v2 API Response

Source: https://alterlab.io/docs/guides/output-formats

This is an example of the structured JSON response you can expect when using the json_v2 format. It includes metadata, sections, tables, and links extracted from the scraped page.

```json
{
  "content": {
    "json_v2": {
      "version": "1.0",
      "extraction_method": "universal",
      "metadata": {
        "title": "How to Build a Web Scraper in Python",
        "description": "A complete guide to building production web scrapers",
        "language": "en",
        "author": { "name": "Jane Doe", "url": "/authors/jane" },
        "dates": {
          "published": "2026-01-15T10:00:00Z",
          "modified": "2026-03-01T14:30:00Z"
        }
      },
      "sections": [
        {
          "id": "section-0",
          "heading": { "text": "How to Build a Web Scraper", "level": 1 },
          "content": [
            { "type": "paragraph", "text": "Web scraping is the process of..." }
          ],
          "children": [
            {
              "id": "section-1",
              "heading": { "text": "Install Dependencies", "level": 2 },
              "content": [
                { "type": "code", "text": "pip install requests", "language": "bash" }
              ],
              "children": []
            }
          ]
        }
      ],
      "tables": [
        {
          "id": "table-0",
          "caption": "Comparison of HTTP Libraries",
          "headers": ["Library", "Async", "Speed"],
          "rows": [
            ["requests", "No", "Fast"],
            ["httpx", "Yes", "Faster"],
            ["aiohttp", "Yes", "Fastest"]
          ],
          "row_count": 3,
          "col_count": 3,
          "has_header": true
        }
      ],
      "links": {
        "navigation": [{ "text": "Home", "url": "/" }],
        "content": [{ "text": "BeautifulSoup docs", "url": "https://..." }],
        "social": [{ "text": "Twitter", "url": "https://twitter.com/...", "platform": "twitter" }],
        "cta": [],
        "external": [],
        "resource": []
      }
    }
  }
}
```

--------------------------------

### Configure Full Data Pipeline with Python

Source: https://alterlab.io/docs/tutorials/data-pipeline

Sets up S3 storage integration, defines an extraction schema, schedules daily batch scraping, and registers a failure webhook.

```python
"""
AlterLab Data Pipeline — Full Setup Script

Creates:
1. S3 storage integration
2. Scheduled batch scrape with extraction schema
3. Auto-export to S3
4. Failure alert webhook

After running, the pipeline executes daily at 06:00 UTC.
"""

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.alterlab.io/api/v1"
headers = {"X-API-Key": API_KEY}

# --- 1. Storage Integration ---
storage = requests.post(
    f"{BASE}/integrations/storage",
    headers=headers,
    json={
        "provider": "s3",
        "name": "pipeline-bucket",
        "bucket": "my-data-pipeline",
        "region": "us-east-1",
        "prefix": "scraping/raw/",
        "credentials": {
            "access_key_id": "AKIAIOSFODNN7EXAMPLE",
            "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLE"
        }
    }
).json()

integration_id = storage["id"]
print(f"[1/4] Storage integration: {integration_id}")

# --- 2. Extraction Schema ---
schema = {
    "type": "object",
    "properties": {
        "product_name": {"type": "string", "description": "Product name"},
        "price": {"type": "number", "description": "Current price"},
        "currency": {"type": "string", "description": "Currency code"},
        "in_stock": {"type": "boolean", "description": "Availability"},
        "rating": {"type": "number", "description": "Rating out of 5"},
        "review_count": {"type": "integer", "description": "Number of reviews"}
    },
    "required": ["product_name", "price", "currency"]
}

# --- 3. Scheduled Batch with Export ---
urls = [
    "https://example.com/products/widget-a",
    "https://example.com/products/widget-b",
    "https://example.com/products/widget-c",
]

schedule = requests.post(
    f"{BASE}/schedules",
    headers=headers,
    json={
        "name": "product-data-pipeline",
        "cron": "0 6 * * *",
        "timezone": "UTC",
        "batch": {
            "urls": [{"url": u} for u in urls],
            "formats": ["json"],
            "extraction_schema": schema,
        },
        "export": {
            "integration_id": integration_id,
            "format": "jsonl",
            "path_template": "products/{date}/{schedule_name}.jsonl"
        }
    }
).json()

print(f"[2/4] Schedule: {schedule['id']}")
print(f"       Next run: {schedule['next_run_at']}")

# --- 4. Failure Webhook ---
webhook = requests.post(
    f"{BASE}/webhooks",
    headers=headers,
    json={
        "url": "https://your-server.com/hooks/pipeline-alerts",
        "events": [
            "schedule.run.failed",
            "schedule.run.partial",
            "schedule.run.completed"
        ],
        "secret": "whsec_your_signing_secret"
    }
).json()

print(f"[3/4] Webhook: {webhook['id']}")
print("[4/4] Pipeline is live. Results export to S3 after each run.")
```

--------------------------------

### AlterLab API Response Example

Source: https://alterlab.io/docs/guides/alerts

This is an example of the JSON response structure when querying alert history from the AlterLab API. It includes details about alerts, their types, messages, and associated data.

```json
{
  "alerts": [
    {
      "id": "a1b2c3d4-ாலத்தில்",
      "alert_rule_id": "550e8400-ாலத்தில்",
      "alert_type": "domain_failure_rate",
      "message": "Failure rate for amazon.com exceeded 50% (63%) in the last 60 minutes",
      "details": {
        "domain": "amazon.com",
        "failure_rate": 63.2,
        "total_requests": 38,
        "failed_requests": 24
      },
      "delivered_via": {
        "email": true,
        "webhook": "delivered"
      },
      "created_at": "2026-03-24T10:15:00Z"
    }
  ],
  "total": 42
}
```

--------------------------------

### Agent Conversation Example

Source: https://alterlab.io/docs/tutorials/ai-agent

This example illustrates a typical conversation flow between a user and an AI research agent, showing the agent's process of scraping, extracting, and reporting on a given topic.

```text
User: Research the current state of web scraping regulations
      in the EU. Include recent court rulings.

Agent: I'll research this topic across multiple sources.

[Calls alterlab_scrape: "https://gdpr.eu/tag/web-scraping/"]
[Calls alterlab_scrape: "https://techcrunch.com/tag/web-scraping/"]
[Calls alterlab_scrape: "https://eur-lex.europa.eu/..." with render_js=true]
[Calls alterlab_extract on legal database with extraction_prompt:
 "Extract case name, date, ruling, and implications for web scraping"]

Agent: Here's my research report:

## EU Web Scraping Regulations - March 2026

### Key Findings
1. GDPR Article 6(1)(f) — legitimate interest basis...
2. Recent CJEU ruling in Case C-xxx/24...
3. ...

### Sources
- [GDPR.eu](https://gdpr.eu/...) — Retrieved March 2026
- [TechCrunch](https://techcrunch.com/...) — Retrieved March 2026
- [EUR-Lex](https://eur-lex.europa.eu/...) — Official text
```

--------------------------------

### Manage API Key Limits and Usage with Python

Source: https://alterlab.io/docs/guides/spend-limits

Demonstrates setting budget limits, checking usage, and fetching timeseries data using the AlterLab Python SDK.

```Python
import alterlab

client = alterlab.AlterLab(api_key="your_api_key")

# Set a $50/month budget limit on a key
key_id = "550e8400-e29b-41d4-a716-446655440000"
client.request(
    "PUT",
    f"/api/v1/api-keys/{key_id}/limits",
    json={
        "budget_limit_microcents": 50_000_000,  # $50.00
        "request_limit": 10_000,
        "reset_period": "monthly",
        "enabled": True,
    },
)

# Check current usage
usage = client.request("GET", f"/api/v1/api-keys/{key_id}/usage?days=30")
spend = usage["total_spend_microcents"] / 1_000_000
print(f"Spend: ${spend:.2f}")
print(f"Requests: {usage['total_requests']}")

# Get daily timeseries for charting
timeseries = client.request(
    "GET", f"/api/v1/api-keys/{key_id}/usage/timeseries?days=7"
)
for day in timeseries["data"]:
    day_spend = day["spend_microcents"] / 1_000_000
    print(f"  {day['date']}: {day['requests']} requests, ${day_spend:.2f}")

# Compare all keys
comparison = client.request("GET", "/api/v1/usage/by-key?days=30")
total = comparison["account_total_spend_microcents"] / 1_000_000
print(f"Account total: ${total:.2f} across {len(comparison['keys'])} keys")
```