Python

The mrscraper-sdk package is a typed Python client for the MrScraper web-scraping API. All client methods are async and must be used with asyncio (or another async runtime).

Installation

Install from PyPI:

pip install mrscraper-sdk

Import the client from the mrscraper package:

from mrscraper import MrScraper

Authentication

Create a client with your MrScraper API token. Get your API token as an environment variable, Get your API key from the MrScraper app. You can learn how to generate an API token in the Generate Token guide.

from mrscraper import MrScraper

client = MrScraper(token="YOUR_MRSCRAPER_API_TOKEN")

The SDK sends this token on each request according to the API authentication rules.

Fetch raw HTML (stealth browser)

Use fetch_html to load a page with the MrScraper stealth browser and return rendered HTML.

import asyncio
from mrscraper import MrScraper

async def main():
    client = MrScraper(token="YOUR_MRSCRAPER_API_TOKEN")

    result = await client.fetch_html(
        "https://example.com/product",
        geo_code="US",
        timeout=120,
        block_resources=False,
    )
    print(result["data"])  # raw HTML string

asyncio.run(main())

Create AI scraper

create_scraper creates and runs an AI-powered scraper from a natural-language instruction. The response includes scraper metadata (including an ID for reruns).

result = await client.create_scraper(
    url="https://example.com/products",
    message="Extract all product names, prices, and ratings",
    agent="listing",  # "general" | "listing" | "map"
    proxy_country="US",
)
scraper_id = result["data"]["data"]["id"]
print("Scraper ID:", scraper_id)

For how agents differ, see AI Scraper agents. The REST surface is aligned with AI scraper init in the API reference.

Agent types

When agent="map", these options apply: max_depth, max_pages, limit, include_patterns, exclude_patterns.

Rerun AI Scraper

Rerun AI Scraper is used to run an existing AI scraper that has already been created on the MrScraper platform, or you can create a scraper first and use its scraper_id. It lets you reuse the same scraper for new URLs without creating a new one.

result = await client.rerun_scraper(
    scraper_id=scraper_id,
    url="https://example.com/products?page=2",
)

For agent="map", you can pass additional parameters to control and limit the crawling scope, such as max_depth, max_pages, limit, include_patterns, and exclude_patterns. These options help you restrict which URLs are visited and how extensively the site is crawled.

Bulk rerun (AI scraper)

Bulk Rerun AI lets you run an existing AI scraper on multiple URLs in one request. Instead of calling rerun_scraper for each URL, you can pass a list and process them all at once, making it faster and reducing API calls.

result = await client.bulk_rerun_ai_scraper(
    scraper_id=scraper_id,
    urls=[
        "https://example.com/products/item1",
        "https://example.com/products/item2",
        "https://example.com/products/item3",
    ],
)

This is more efficient than calling rerun_scraper once per URL. Consolidated job metadata is in the response; use results to read per-URL outcomes.

Rerun manual scraper

Rerun manual Scraper is used to run an existing manual scraper that has already been created on the MrScraper platform, or you can create a scraper first and use its scraper_id. It lets you reuse the same scraper for new URLs without creating a new one.

result = await client.rerun_manual_scraper(
    scraper_id="manual_scraper_67890",
    url="https://example.com/products/new-item",
)

See Manual rerun in the API docs for the underlying contract.

Bulk rerun (manual scraper)

Bulk Rerun manual lets you run an existing manual scraper on multiple URLs in one request. Instead of calling rerun_scraper for each URL, you can pass a list and process them all at once, making it faster and reducing API calls.

result = await client.bulk_rerun_manual_scraper(
    scraper_id="scraper_12345",
    urls=[
        "https://www.example.com/products/item1",
        "https://www.example.com/products/item2",
        "https://www.example.com/products/item3",
    ],
)

The response includes bulk job information (for example job id and status). Poll or list results with get_all_results as needed.

Retrieve results

Get All Results in Range

page = await client.get_all_results(
    sort_field="updatedAt",
    sort_order="DESC",
    page_size=20,
    page=1,
    search="product",
    date_range_column="updatedAt",
    start_at="2026-01-01",
    end_at="2026-01-31",
)
print(page["data"])

This method gets results within a specific date range.

• You can control sorting and pagination using sort_field, sort_order, page_size, and page.
• Use start_at and end_at to filter by date.

Notes:

• The search parameter is optional — you can remove it if you don’t need keyword filtering.
• If you already know the exact target (like a URL), you don’t need to use search.

Related REST docs: Get All Results in Range.

Get Result by ID

result = await client.get_result_by_id("result_12345")
print(result["data"])

This method retrieves a single result using its unique ID.

• Replace "result_12345" with the actual result ID.
• It returns detailed data for that specific result.

Use this when you already know the exact result you want. Related REST docs: Result detail.

API reference (MrScraper)

Every method is a coroutine—always await it.

Error handling

The SDK raises typed exceptions from mrscraper.exceptions:

from mrscraper.exceptions import AuthenticationError, APIError, NetworkError

try:
    result = await client.fetch_html("https://example.com")
except AuthenticationError:
    print("Check your API token at https://app.mrscraper.com")
except APIError as e:
    print(f"API error {e.status_code}: {e}")
except NetworkError as e:
    print(f"Network problem: {e}")

Mapping from Firecrawl

If you are coming from the Firecrawl Python SDK, the following table maps common Firecrawl flows to MrScraper.

License

The package is published under the MIT License; see the PyPI project page for full metadata and links to the repository.