### Quick Start Example

Source: https://docs.mrscraper.com/docs/integrations/node

Demonstrates fetching raw HTML and creating an AI scraper using the SDK.

```javascript
import {
  fetchHtml,
  createAiScraper,
  MrScraperError,
} from "@mrscraper/sdk";

try {
  // 1. Fetch raw HTML from a URL
  const html = await fetchHtml({
    url: "https://example.com",
  });
  console.log(html);

  // 2. Create an AI scraper (listing agent)
  const scraper = await createAiScraper({
    url: "https://example.com/products",
    message: "Extract all product names and prices",
    agent: "listing",
  });
  console.log(scraper);
  
} catch (err) {
  if (err instanceof MrScraperError) {
    console.error(`[${err.status ?? "network"}] ${err.message}`);
  } else {
    throw err;
  }
}
```

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

### Install Dependencies

Source: https://docs.mrscraper.com/docs/residential-proxy/examples/nodejs

Required packages for the provided Node.js proxy examples.

```bash
npm install axios cheerio puppeteer
```

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

### Install and Verify CLI

Source: https://docs.mrscraper.com/docs/getting-started/cli

Install the CLI globally via npm and verify the installation.

```bash
npm install -g @mrscraper/cli
mrscraper --help
```

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

### Install Prerequisites

Source: https://docs.mrscraper.com/docs/integrations/langchain

Install the necessary LangGraph and LangChain OpenAI packages.

```bash
pip install langgraph langchain-openai
```

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

### Install HTTParty Gem

Source: https://docs.mrscraper.com/docs/residential-proxy/examples/ruby

Required dependency for the HTTParty examples.

```bash
gem install httparty
```

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

### Custom Session Duration Example

Source: https://docs.mrscraper.com/docs/residential-proxy/configuration/authentication

Example of a 30-minute session configuration.

```text
# Session lasts 30 minutes
user123-country-jp-sessid-x9-sesstime-30:pass456@proxy.mrscraper.com:10000
```

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

### Install MrScraper SDK

Source: https://docs.mrscraper.com/docs/integrations/python

Use pip to install the package from PyPI.

```bash
pip install mrscraper-sdk
```

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

### 404 Not Found Error Example

Source: https://docs.mrscraper.com/docs/api/error-handling

Example response when a requested entity does not exist.

```json
{
  "message": "Resource not found",
  "error": "Not Found"
}
```

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

### Session-Based Static Proxy Example

Source: https://docs.mrscraper.com/docs/residential-proxy/configuration/authentication

Example of a static session ID configuration.

```text
# Session ID: alpha1
user123-country-us-sessid-alpha1:pass456@proxy.mrscraper.com:10000
```

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

### Install CLI from Source

Source: https://docs.mrscraper.com/docs/getting-started/cli

Clone the repository and run the CLI directly from the source code.

```bash
git clone https://github.com/mrscraper-com/cli.git
cd cli
npm install
node bin/mrscraper.js --help
```

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

### Initialize MrScraper

Source: https://docs.mrscraper.com/docs/getting-started/cli

Perform first-time setup with a welcome message.

```bash
mrscraper init
```

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

### Install Dependencies

Source: https://docs.mrscraper.com/docs/residential-proxy/examples/python

Required packages for using the proxy with requests and BeautifulSoup.

```bash
pip install requests beautifulsoup4
```

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

### Install SDK

Source: https://docs.mrscraper.com/docs/integrations/node

Use npm to install the official MrScraper SDK package.

```bash
npm install @mrscraper/sdk
```

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

### Example Proxy Authentication String

Source: https://docs.mrscraper.com/docs/residential-proxy/configuration/country-codes

A concrete example of a proxy username configured for the United States.

```text
user123-country-us:pass456@proxy.mrscraper.com:10000
```

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

### Install langchain-mrscraper

Source: https://docs.mrscraper.com/docs/integrations/langchain

Install the package and its dependencies using pip.

```bash
pip install -U langchain-mrscraper
```

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

### Static Proxy Implementation

Source: https://docs.mrscraper.com/docs/residential-proxy/configuration/proxy-types

Example of using a static proxy with a 30-minute session duration in Python.

```python
import requests

# Static proxy with 30-minute session
proxy = {
    'http': 'http://user-country-us-sessid-stable1-sesstime-30:pass@proxy.mrscraper.com:10000',
    'https': 'http://user-country-us-sessid-stable1-sesstime-30:pass@proxy.mrscraper.com:10000'
}

# All requests use the same IP
for i in range(10):
    response = requests.get('https://api.ipify.org', proxies=proxy)
    print(f"Request {i+1}: {response.text}")  # Same IP every time
```

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

### API Response Examples

Source: https://docs.mrscraper.com/docs/api/v3/analytic/proxy

Examples of successful and error response bodies returned by the bandwidth endpoint.

```json
[
  {
    "username": "john",
    "total_bandwidth_usage": 99.384
  },
  {
    "username": "jane",
    "total_bandwidth_usage": 31.022
  }
]
```

```json
{
  "message": "startDate is required and must be in `yyyy-MM-dd HH:mm:ss` format",
  "error": "Bad Request",
  "statusCode": 400
}
```

```json
{
  "message": "Unauthorized access",
  "error": "Unauthorized"
}
```

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

### Listing Agent JSON Output Example

Source: https://docs.mrscraper.com/docs/features/ai-scraper/listing

Example of the structured JSON output generated by the Listing Agent, showing data extracted across multiple pages.

```json
{
    "response": [
        {
        "page_num": 0,
        "data": {
            "mode": "direct",
            "data": [
            {
                "id": "74301965",
                "address": "80 Emerald Street, Manchester, NH 03103",
                "agent_company": "Listing provided by PrimeMLS",
                "price": "$364,900",
                "bedrooms": "3",
                "bathrooms": "2",
                "sqft": "1",
                "status": "Active",
                "url": "https://www.zillow.com/homedetails/80-Emerald-St-Manchester-NH-03103/74301965_zpid/",
                "highlight": "14 hours ago"
            },
            {
                "id": "121734329",
                "address": "21 School Street, New Portland, ME 04961",
                "agent_company": "KELLER WILLIAMS REALTY",
                "price": "$449,000",
                "bedrooms": "2",
                "bathrooms": "1",
                "sqft": "1",
                "status": "Active",
                "url": "https://www.zillow.com/homedetails/21-School-St-New-Portland-ME-04961/121734329_zpid/",
                "highlight": "18 hours ago"
            },
            ...
            ]
        }
        },
        {
        "page_num": 1,
        "data": {
            "mode": "direct",
            "data": [
            {
                "id": "458007902",
                "address": "Lot 59&60 Starks Road, New Sharon, ME 04955",
                "agent_company": "COLDWELL BANKER SANDY RIVER REALTY",
                "price": "$420,000",
                "bedrooms": null,
                "bathrooms": null,
                "sqft": "92 acres lot",
                "status": "Active",
                "url": "https://www.zillow.com/homedetails/LOT-5960-Starks-Rd-New-Sharon-ME-04955/458007902_zpid/",
                "highlight": "Open fields"
            },
            {
                "id": "91905999",
                "address": "3 Long Cove Road, York, ME 03909",
                "agent_company": "LEGACY PROPERTIES SOTHEBY'S INTERNATIONAL REALTY",
                "price": "$1,795,000",
                "bedrooms": "3",
                "bathrooms": "2",
                "sqft": "2",
                "status": "Active",
                "url": "https://www.zillow.com/homedetails/3-Long-Cove-Rd-York-ME-03909/91905999_zpid/",
                "highlight": "Modern comforts"
            }
            ...
            ],
            "link": "https://www.zillow.com/me/?searchQueryState=%7B%22isMapVisible%22%3Atrue..."
        }
        }
    ]
}
```

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

### Bulk scraping response examples

Source: https://docs.mrscraper.com/docs/guides/programmatically

Example JSON responses for running and finished bulk scraping tasks.

```json
{
  "message": "Successful operation!",
  "data": {
    "id": "YOUR_BULK_RESULT_ID",
    "status": "Running",
    "data": null
  }
}
```

```json
{
  "message": "Successful operation!",
  "data": {
    "createdAt": "2026-01-18T08:38:23.993Z",
    "id": "YOUR_BULK_RESULT_ID",
    "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "scraperId": "YOUR_DETAIL_SCRAPER_ID",
    "type": "Bulk-AI",
    "status": "Finished",
    "tokenUsage": 12,
    "data": {
      "mergedData": [
        {
          "title": "A Light in the Attic",
          "price": "£51.77",
          "availability": "In stock (22 available)",
          "description": "It's hard to imagine a world without A Light in the Attic...",
          "product_type": "Books",
          "upc": "a897fe39b1053632",
          "price_excl_tax": "£51.77",
          "price_incl_tax": "£51.77",
          "tax": "£0.00",
          "number_of_reviews": "0"
        },
        {
          "title": "Tipping the Velvet",
          "price": "£53.74",
          "availability": "In stock (20 available)",
          "description": "Erotic and absorbing...Written with starling power...",
          "product_type": "Books",
          "upc": "90fa61229261140a",
          "price_excl_tax": "£53.74",
          "price_incl_tax": "£53.74",
          "tax": "£0.00",
          "number_of_reviews": "0"
        },
        {
          "title": "Soumission",
          "price": "£50.10",
          "availability": "In stock (20 available)",
          "description": "Dans une France assez proche de la nôtre...",
          "product_type": "Books",
          "upc": "6957f44c3847a760",
          "price_excl_tax": "£50.10",
          "price_incl_tax": "£50.10",
          "tax": "£0.00",
          "number_of_reviews": "0"
        }
      ],
      "urlDetails": [
        {
          "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
          "status": "Finished",
          "error": ""
        },
        {
          "url": "https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html",
          "status": "Finished",
          "error": ""
        },
        {
          "url": "https://books.toscrape.com/catalogue/soumission_998/index.html",
          "status": "Finished",
          "error": ""
        }
      ],
      "summary": {
        "totalUrls": 3,
        "successfulUrls": 3,
        "failedUrls": 0,
        "totalTokenUsage": 12
      }
    }
  }
}
```

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

### Complete Programmatic Workflow

Source: https://docs.mrscraper.com/docs/guides/programmatically

An end-to-end example demonstrating the full scraping lifecycle from URL collection to result retrieval.

```javascript
(async () => {
  console.log("🚀 Starting N2N Programmatic Workflow\n");
  console.log("=".repeat(60));
  
  // Step 1: Verify token
  if (!await step1VerifyToken()) {
    process.exit(1);
  }
  
  // Step 2: Collect URLs
  const url = "https://books.toscrape.com";
  const { urls: initialUrls, scraperId: urlScraperId } = await step2CollectUrls(
    url,
    "Return array of urls that follow patterns https://books.toscrape.com/catalogue but exclude that has patterns https://books.toscrape.com/catalogue/category"
  );
  
  // Step 3: Rerun URL collection scraper
  let urls = [];
  if (urlScraperId) {
    urls = await step3RerunCollectUrls(url, urlScraperId);
  }
  
  if (!urls.length) {
    process.exit(1);
  }
  
  // Use first 3 URLs for demo
  urls = urls.slice(0, 3);
  console.log(`  Using ${urls.length} URLs for demo`);
  
  // Step 4: Create detail scraper
  const detailScraperId = await step4CreateDetailScraper(
    urls[0],
    "Extract all data detail"
  );
  
  if (!detailScraperId) {
    process.exit(1);
  }
  
  // Step 5: Bulk scrape
  let bulkResultId = await step5BulkScrape(detailScraperId, urls);
  
  // Optional: Uncomment to use a specific bulk result ID
  // bulkResultId = "a438e4c2-8489-4473-b405-6b4b5e18ed3f";
  
  // Step 6: Get results
  const results = await step6GetResults(bulkResultId);
  
  if (results) {
    console.log("\n" + "=".repeat(60));
    console.log("📊 RESULTS SUMMARY");
    console.log("=".repeat(60));
    console.log(`✓ Total items: ${results.mergedData.length}`);
    console.log(`✓ Successful: ${results.summary.successfulUrls}`);
    console.log(`✓ Failed: ${results.summary.failedUrls}`);
    console.log(`✓ Tokens used: ${results.summary.totalTokenUsage}`);
    
    console.log("\n📦 EXTRACTED DATA:");
    console.log(JSON.stringify(results.mergedData, null, 2));
  }
})();
```

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

### 403 Forbidden Error Example

Source: https://docs.mrscraper.com/docs/api/error-handling

Example response when the token lacks permission for the requested resource.

```json
{
  "message": "You do not have permission to access this resource",
  "error": "Forbidden"
}
```

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

### Install and use MrScraper CLI

Source: https://docs.mrscraper.com/docs/getting-started/cli

Global installation and basic usage for scraping a webpage with AI prompts.

```bash
# 1. Install globally
npm install -g @mrscraper/cli

# 2. Login
mrscraper login

# 3. Scrape a webpage
mrscraper scrape "https://www.ebay.com/itm/266727555514" \
  --prompt "get name, price, features/description, images, seller, and shipping"
```

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

### Node.js Custom Session Duration Example

Source: https://docs.mrscraper.com/docs/residential-proxy/configuration/authentication

Demonstrates using axios with a 20-minute session proxy configuration.

```javascript
const axios = require('axios');

// 20-minute session proxy
const proxy = {
  host: 'proxy.mrscraper.com',
  port: 10000,
  auth: {
    username: 'user123-country-us-sessid-node_session-sesstime-20',
    password: 'pass456'
  }
};

async function testProxy() {
  for (let i = 0; i < 10; i++) {
    const response = await axios.get('https://api.ipify.org', { proxy });
    console.log(`Request ${i+1}: ${response.data}`);
    
    // Wait 2 minutes between requests
    await new Promise(resolve => setTimeout(resolve, 120000));
  }
}

testProxy();
```

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

### Run CLI Without Installation

Source: https://docs.mrscraper.com/docs/getting-started/cli

Execute CLI commands directly using npx without a permanent global installation.

```bash
npx @mrscraper/cli --help
npx @mrscraper/cli scrape "https://example.com/"
```

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

### 429 Too Many Requests Error Example

Source: https://docs.mrscraper.com/docs/api/error-handling

Example response when rate limits are exceeded.

```json
{
  "message": "Too many requests. Please try again later."
}
```

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

### 400 Bad Request Error Example

Source: https://docs.mrscraper.com/docs/api/error-handling

Example response when a request body is malformed or missing required parameters.

```json
{
  "message": "startDate is required and must be in `yyyy-MM-dd HH:mm:ss` format",
  "error": "Bad Request"
}
```

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

### Default Proxy cURL Example

Source: https://docs.mrscraper.com/docs/residential-proxy/configuration/authentication

A basic cURL command demonstrating the default proxy authentication.

```bash
curl -x "user123:pass456@proxy.mrscraper.com:10000" https://api.ipify.org
```

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

### Analytic Statuses Response Examples

Source: https://docs.mrscraper.com/docs/api/v3/analytic/status

Examples of successful and unauthorized response bodies returned by the API.

```json
{
  "message": "Successful operation!",
  "data": {
    "countAll": 35,
    "successRate": 100,
    "reqPerMinute": 0.00023597785853464491,
    "avgLatency": 0,
    "data": [
      {
        "key": "PENDING",
        "value": 0
      },
      {
        "key": "RUNNING",
        "value": 0
      },
      {
        "key": "PROCESSING",
        "value": 0
      },
      {
        "key": "COMPLETED",
        "value": "35"
      },
      {
        "key": "FAILED",
        "value": 0
      },
      {
        "key": "CANCELLED",
        "value": 0
      }
    ]
  }
}
```

```json
{
  "message": "Unauthorized access",
  "error": "Unauthorized"
}
```

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

### Proxy Configuration Examples

Source: https://docs.mrscraper.com/docs/residential-proxy/examples/overview

Standard proxy connection strings for different routing requirements including random country, static, and session-based configurations.

```text
# Random country, rotating IP
user:password@proxy.mrscraper.com:10000
```

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

### Advanced AI scraping examples

Source: https://docs.mrscraper.com/docs/getting-started/cli

Specific use cases for product extraction, multi-page listings, and site mapping.

```bash
# Product page extraction
mrscraper scrape "https://www.ebay.com/itm/266727555514" \
  --prompt "get name, price, features, images, seller, and shipping"

# Multi-page listing
mrscraper scrape "https://books.toscrape.com/catalogue/category/books_1/index.html" \
  --agent listing \
  --prompt "Extract book title, price, and availability" \
  --max-pages 3

# Website mapping
mrscraper scrape "https://docs.mrscraper.com" \
  --agent map \
  --include-patterns "/docs/.*" \
  --exclude-patterns "/admin"
```

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

### AI Assistant Prompt Example

Source: https://docs.mrscraper.com/docs/features/manual-scraper

A sample prompt used to instruct the AI Assistant to extract specific data points from a target URL.

```text
Extract the book title and rating from the page.
```

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

### Manual Workflow Output Example

Source: https://docs.mrscraper.com/docs/features/manual-scraper

The JSON structure returned by the scraper after executing the custom injection script.

```json
{
  "data": {
    "...",
    "product": {
      "...",
      "price": {
        "formatted_comparison_price": "$349.99",
        "formatted_comparison_price_type": "reg",
        "formatted_current_price": "$165.99 - $169.99",
        "formatted_current_price_type": "sale",
        "location_id": 3991,
        "current_retail_min": 165.99,
        "reg_retail_max": 349.99
      }
      "...",
    }
    "...",
  }
}
```

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

### Verify API Token and Subscription Status

Source: https://docs.mrscraper.com/docs/guides/programmatically

Use these examples to authenticate with your API token and retrieve your current subscription account details.

```bash
curl --location 'https://api.app.mrscraper.com/api/v1/subscription-accounts' \
--header 'accept: */*' \
--header 'x-api-token: <MRSCRAPER_API_TOKEN>'
```

```javascript
const token = "MRSCRAPER_API_TOKEN";

fetch("https://api.app.mrscraper.com/api/v1/subscription-accounts", {
  method: "GET",
  headers: {
    "accept": "*/*",
    "x-api-token": token
  }
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

```python
import requests

token = "MRSCRAPER_API_TOKEN"

headers = {
    "accept": "*/*",
    "x-api-token": token
}

response = requests.get(
    "https://api.app.mrscraper.com/api/v1/subscription-accounts",
    headers=headers
)

print(response.json())
```

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

### Query Scraped Data in PostgreSQL

Source: https://docs.mrscraper.com/docs/integrations/sql

Example of retrieving data from the database table after the scraper has successfully populated it.

```sql
scraping=# select * from books;
                 title
---------------------------------------
 A Light in the ...
 Tipping the Velvet
 Soumission
 Sharp Objects
 Sapiens: A Brief History ...
 The Requiem Red
 The Dirty Little Secrets ...
 The Coming Woman: A ...
 The Boys in the ...
 The Black Maria
 Starving Hearts (Triangular Trade ...
 Shakespeare’s Sonnets
 Set Me Free
 Scott Pilgrim’s Precious Little ...
 Rip it Up and ...
 Our Band Could Be ...
 Olio
 Mesaerion: The Best Science ...
 Libertarianism for Beginners
 It’s Only the Himalayas
(20 rows)
```

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

### API Response Examples

Source: https://docs.mrscraper.com/docs/api/v3/scraper/unblocker-scraping

Standard response formats for successful requests and various error conditions.

```json
"string"
```

```json
{
  "message": "Unauthorized access",
  "error": "Unauthorized"
}
```

```json
{
  "message": "You do not have permission to access this resource",
  "error": "Forbidden",
  "statusCode": 403
}
```

```json
{
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422
}
```

```json
{
  "message": "Too many requests. Please try again later."
}
```

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

### Shein PDP Scraper Response

Source: https://docs.mrscraper.com/docs/api/ecommerce/shein/scraper

Example of a successful JSON response containing product information, stock status, and store labels.

```json
{
  "success": true,
  "message": "Succesfully scraped",
  "data": {
    "code": "0",
    "msg": "ok",
    "info": {
      "multiPropertyProducts": [],
      "productInfo": {
        "selectedMallCode": "1",
        "cccDetailsTemplate": {
          "content": [
            {
              "detailImg": "1",
              "sizeChart": "1",
              "description": "1",
              "countCell": "1",
              "imgSrc": "",
              "colorType": "2"
            }
          ],
          "tempCode": "",
          "tempType": "1"
        },
        "returnType": "2",
        "isCodLargeProduct": "0",
        "qtyTipsType": "3",
        "goods_id": "194788155",
        "goods_sn": "sc2306243993144424",
        "is_on_sale": "1",
        "stock": "0",
        "customization_attributes": {
          "customization_flag": 0,
          "customize_url": null,
          "customize_article_url": null,
          "customization_platfrom_flag": null
        },
        "is_saved": "0",
        "is_support_return": "2",
        "return_title": "لا يمكن إرجاع أو استبدال المنتجات في هذه الفئة.",
        "cod_title": "خدمة الدفع عند الاستلام"
      },
      "productLabel": {
        "goodsImgBenefitInfo": {
          "title": "Why Choose Us?",
          "isFreeReturn": "0",
          "freeReturnTips": null,
          "freeReturnDetailTips": null
        },
        "hotNews": [],
        "carHotNews": [],
        "storeQualityList": [
          {
            "tagType": "5",
            "multiLanguageValue": "99K+ تم البيع مؤخراً",
            "icon": "https://img.shein.com/v4/p/shein/2025/10/22/8f/176112598930e6f1df6b324ff5ebd037bd376d5332.png"
          },
          {
            "tagType": "6",
            "multiLanguageValue": "37K+ إعادة الشراء",
            "icon": "https://img.shein.com/v4/p/shein/2025/10/22/62/1761125901e63f428173906012b9c81c1f196d8898.png"
          }
        ],
        "storeTipList": [
          {
            "popType": "1",
            "multiLanguage": "{0} تم دفع {1}",
            "nameTip": "9***7",
            "timeTip": "قبل 10 ساعة",
            "popTypeLength": 3
          },
          {
            "popType": "3",
            "multiLanguage": "{0} تمت متابعة {1}",
            "nameTip": "l***2",
            "timeTip": "منذ 1 يوم",
            "popTypeLength": 3
          },
          {
            "popType": "2",
            "multiLanguage": "{0} تتصفح",
            "nameTip": "m***3",
            "timeTip": "",
            "popTypeLength": 3
          },
          {
            "popType": "1",
            "multiLanguage": "{0} تم دفع {1}",
            "nameTip": "a***b",
            "timeTip": "منذ 1 يوم",
            "popTypeLength": 3
          },
          {
            "popType": "3",
            "multiLanguage": "{0} تمت متابعة {1}",
            "nameTip": "d***1",
            "timeTip": "منذ 1 يوم",
            "popTypeLength": 3
          },
          {
            "popType": "2",
            "multiLanguage": "{0} تتصفح",
            "nameTip": "c***0",
            "timeTip": "",
            "popTypeLength": 3
          },
          {
            "popType": "1",
            "multiLanguage": "{0} تم دفع {1}",
            "nameTip": "t***r",
            "timeTip": "منذ 1 يوم",
            "popTypeLength": 3
          },
          {
            "popType": "3",
            "multiLanguage": "{0} تمت متابعة {1}",
            "nameTip": "y***0",
            "timeTip": "منذ 1 يوم",
            "popTypeLength": 3
          },
          {
            "popType": "2",
            "multiLanguage": "{0} تتصفح",
            "nameTip": "k***4",
            "timeTip": "",
            "popTypeLength": 3
          },
          {
            "popType": "1",
            "multiLanguage": "{0} تم دفع {1}",
            "nameTip": "9***7",
            "timeTip": "منذ 1 يوم",
            "popTypeLength": 3
          },
          {
            "popType": "3",
            "multiLanguage": "{0} تمت متابعة {1}",
            "nameTip": "l***o",
            "timeTip": "منذ 1 يوم",
            "popTypeLength": 3
          }
        ]
      }
    }
  }
}
```

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

### View Manual Scraper Output with Cookies

Source: https://docs.mrscraper.com/docs/features/manual-scraper

Example JSON structure showing the inclusion of a cookies field when the Get Cookies option is enabled.

```json
{
  "books_data": [
    {
      "title": "A Light in the Attic",
      "rating": "Three"
    }
  ],
  "cookies": []
}
```

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

### Walmart PDP Scraper Response Format

Source: https://docs.mrscraper.com/docs/api/ecommerce/walmart/pdp-scraper

Example of a successful JSON response containing product details such as price, rating, and store information.

```json
{
  "success": true,
  "message": "Succesfully scraped",
  "data": {
    "mrp": "$1,599.00",
    "price": "$459.99",
    "rating": "5 stars out of 87 reviews",
    "seller": "82days Tech",
    "reviews": "87 reviews",
    "location": "1885 STATE ROUTE 57 STE 100, Hackettstown, NJ 07840",
    "statusText": "In stock",
    "deliverDays": "Arrives by in 7 days",
    "productName": "HP 14\" Laptop Student Business Computer, Intel N150 Processor, 1-Year Microsoft 365, 32GB RAM, 128GB UFS, 256GB Micro SD Card, Copilot AI, Windows 11 Pro",
    "storeDetails": {
      "storeName": "82days Tech",
      "storeType": "MARKETPLACE",
      "storeRating": "3.8 stars out of 5, based on 81 seller reviews"
    }
  }
}
```

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

### Perform Paginated Requests with cURL

Source: https://docs.mrscraper.com/docs/api/pagination

Examples of retrieving paginated results using standard, search-filtered, and date-filtered queries.

```bash
curl -X GET "https://api.app.mrscraper.com/api/v1/results?page=1&pageSize=10&sortField=updatedAt&sortOrder=DESC" \
  -H "x-api-token: MRSCRAPER_API_TOKEN" \
  -H "accept: application/json"
```

```bash
curl -X GET "https://api.app.mrscraper.com/api/v1/results?page=1&pageSize=10&sortField=updatedAt&sortOrder=DESC&search=example.com" \
  -H "x-api-token: MRSCRAPER_API_TOKEN" \
  -H "accept: application/json"
```

```bash
curl -X GET "https://api.app.mrscraper.com/api/v1/results?page=1&pageSize=10&sortField=updatedAt&sortOrder=DESC&dateRangeColumn=createdAt&startAt=2025-11-13T00:00:00.000Z&endAt=2025-11-14T23:59:59.999Z" \
  -H "x-api-token: MRSCRAPER_API_TOKEN" \
  -H "accept: application/json"
```

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

### GET /

Source: https://docs.mrscraper.com/docs/features/unblocker

Scrape a target website using the Web Unblocker service with optional browser rendering and proxy configuration.

```APIDOC
## GET /

### Description
Scrape a target website using the Web Unblocker service. This endpoint supports headless browser rendering, geo-targeting, and custom wait conditions.

### Method
GET

### Endpoint
https://api.app.mrscraper.com/

### Parameters
#### Query Parameters
- **url** (string) - Required - Target website URL to scrape.
- **token** (string) - Required - Your API authentication token.
- **browserRendering** (boolean) - Optional - Render the page in a headless browser. Default: false.
- **geoCode** (string) - Optional - ISO 3166-1 alpha-2 country code used for proxy routing.
- **timeout** (integer) - Optional - Maximum number of seconds to wait for page loading. Default: 30.
- **waitForSelector** (string) - Optional - CSS selector to wait for before returning the page content. Requires browserRendering=true.
- **homePage** (boolean) - Optional - Visit the website's home page before navigating to the target URL. Default: false.
- **blockResources** (boolean) - Optional - Block non-essential resources to improve performance. Supported only by compatible proxies.
- **maxRetries** (integer) - Optional - Maximum number of retry attempts if the scrape fails. Default: 3.
- **tokenCap** (integer) - Optional - Maximum number of tokens that can be consumed across retry attempts.

### Request Example
curl -X GET "https://api.app.mrscraper.com/?url=https%3A%2F%2Fwww.amazon.com%2Fstores%2Fluxurystores%2Fpage%2FB6BC6264-7221-424B-9191-DAE2BCF963A2&token=atk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&timeout=120&geoCode=pt&browserRendering=true&waitForSelector=div%5Bdata-testid%3D%22grid-item-info%22%5D&homePage=false&blockResources=true&maxRetries=3&tokenCap=10" -H "x-api-token: MRSCRAPER_API_KEY"
```

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

### Initialize Individual Tools

Source: https://docs.mrscraper.com/docs/integrations/langchain

Directly instantiate specific tools using their respective constructor classes.

```python
from langchain_mrscraper.tools import MrScraperFetchHtmlTool

fetch_html = MrScraperFetchHtmlTool(token="MRSCRAPER_API_TOKEN")
```

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

### Listing Agent JSON Output

Source: https://docs.mrscraper.com/docs/features/ai-scraper/listing

Example of structured output from the Listing Agent, including pagination metadata and detail page URLs.

```json
{
"response": [
    {
    "page_num": 0,
    "data": {
        "mode": "direct",
        "data": [
        {
            "id": "74301965",
            "address": "80 Emerald Street, Manchester, NH 03103",
            "agent_company": "Listing provided by PrimeMLS",
            "price": "$364,900",
            "bedrooms": "3",
            "bathrooms": "2",
            "sqft": "1",
            "status": "Active",
            "url": "https://www.zillow.com/homedetails/80-Emerald-St-Manchester-NH-03103/74301965_zpid/",
            "highlight": "14 hours ago"
        },
        {
            "id": "121734329",
            "address": "21 School Street, New Portland, ME 04961",
            "agent_company": "KELLER WILLIAMS REALTY",
            "price": "$449,000",
            "bedrooms": "2",
            "bathrooms": "1",
            "sqft": "1",
            "status": "Active",
            "url": "https://www.zillow.com/homedetails/21-School-St-New-Portland-ME-04961/121734329_zpid/",
            "highlight": "18 hours ago"
        },
        ...
        ]
    }
    },
    {
    "page_num": 1,
    "data": {
        "mode": "direct",
        "data": [
        {
            "id": "458007902",
            "address": "Lot 59&60 Starks Road, New Sharon, ME 04955",
            "agent_company": "COLDWELL BANKER SANDY RIVER REALTY",
            "price": "$420,000",
            "bedrooms": null,
            "bathrooms": null,
            "sqft": "92 acres lot",
            "status": "Active",
            "url": "https://www.zillow.com/homedetails/LOT-5960-Starks-Rd-New-Sharon-ME-04955/458007902_zpid/",
            "highlight": "Open fields"
        },
        {
            "id": "91905999",
            "address": "3 Long Cove Road, York, ME 03909",
            "agent_company": "LEGACY PROPERTIES SOTHEBY'S INTERNATIONAL REALTY",
            "price": "$1,795,000",
            "bedrooms": "3",
            "bathrooms": "2",
            "sqft": "2",
            "status": "Active",
            "url": "https://www.zillow.com/homedetails/3-Long-Cove-Rd-York-ME-03909/91905999_zpid/",
            "highlight": "Modern comforts"
        }
        ...
        ],
        "link": "https://www.zillow.com/me/?searchQueryState=%7B%22isMapVisible%22%3Atrue..."
    }
    }
]
}
```

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

### Initialize MrScraperToolkit

Source: https://docs.mrscraper.com/docs/integrations/langchain

Load all available tools using the toolkit class, either via environment variables or an explicit API token.

```python
from langchain_mrscraper import MrScraperToolkit

# Using environment variable
tools = MrScraperToolkit().get_tools()

# Or with explicit token
tools = MrScraperToolkit(token="MRSCRAPER_API_TOKEN").get_tools()
```

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

### Create a detail scraper via API

Source: https://docs.mrscraper.com/docs/guides/programmatically

Use these examples to initiate a detail extraction task. Ensure you replace the placeholder token with your actual API token.

```bash
curl --location 'https://api.app.mrscraper.com/api/v1/scrapers-ai' \
--header 'accept: application/json' \
--header 'x-api-token: <MRSCRAPER_API_TOKEN>' \
--header 'content-type: application/json' \
--data '{
    "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
    "agent": "general",
    "message": "Extract data : Title, Product Description, Price (Float), Availability, and Number of reviews",
    "proxyCountry": ""
}'
```

```javascript
const token = "MRSCRAPER_API_TOKEN";

fetch("https://api.app.mrscraper.com/api/v1/scrapers-ai", {
  method: "POST",
  headers: {
    "accept": "application/json",
    "x-api-token": token,
    "content-type": "application/json"
  },
  body: JSON.stringify({
    url: "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
    agent: "general",
    message: "Extract data : Title, Product Description, Price (Float), Availability, and Number of reviews",
    proxyCountry: ""
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

```python
import requests

token = "MRSCRAPER_API_TOKEN"

url = "https://api.app.mrscraper.com/api/v1/scrapers-ai"
headers = {
    "accept": "application/json",
    "x-api-token": token,
    "content-type": "application/json"
}
payload = {
    "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
    "agent": "general",
    "message": "Extract data : Title, Product Description, Price (Float), Availability, and Number of reviews",
    "proxyCountry": ""
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

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

### Mobile Proxy Example

Source: https://docs.mrscraper.com/docs/residential-proxy/configuration/authentication

Example of targeting US mobile carrier IPs.

```text
# US mobile carrier IPs
user123-mobile-country-us:pass456@proxy.mrscraper.com:10000
```

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

### 422 Unprocessable Entity Error Example

Source: https://docs.mrscraper.com/docs/api/error-handling

Example response when a request fails validation.

```json
{
  "message": "Validation failed",
  "error": "Unprocessable Entity"
}
```

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

### Country-Specific Proxy Example

Source: https://docs.mrscraper.com/docs/residential-proxy/configuration/authentication

Example of targeting US proxies using the country-specific format.

```text
# Target US proxies
user123-country-us:pass456@proxy.mrscraper.com:10000
```

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

### Create AI Scraper

Source: https://docs.mrscraper.com/docs/integrations/python

Initialize an AI-powered scraper with natural language instructions.

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

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

### Basic HTTP Request with Net::HTTP

Source: https://docs.mrscraper.com/docs/residential-proxy/examples/ruby

Fundamental setup using Ruby's built-in Net::HTTP library with a static proxy session.

```ruby
require 'net/http'
require 'uri'

# Static proxy configuration
proxy_uri = URI.parse('http://user-country-us-sessid-ruby1:pass123@proxy.mrscraper.com:10000')

uri = URI.parse('https://api.ipify.org')

http = Net::HTTP.new(uri.host, uri.port, 
                     proxy_uri.host, proxy_uri.port, 
                     proxy_uri.user, proxy_uri.password)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
response = http.request(request)

puts "Your IP: #{response.body}"
```

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

### Initialize MrScraper Client

Source: https://docs.mrscraper.com/docs/integrations/python

Configure the client with your API token. Environment variables are recommended for security.

```python
from mrscraper import MrScraper

client = MrScraper(token="MRSCRAPER_API_TOKEN")
```

```python
import os
from mrscraper import MrScraper

client = MrScraper(token=os.getenv("MRSCRAPER_API_TOKEN"))
```

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

### Extract Detailed Data with General Agent

Source: https://docs.mrscraper.com/docs/features/ai-scraper/multi-agent-flow/list

Input configuration and sample output for extracting comprehensive product specifications from a specific URL.

```json
// Input (for each URL)
{
  "url": "https://www.walmart.com/ip/123456789",
  "agent": "general",
  "prompt": "Extract laptop specifications including processor, RAM, storage, display, graphics, ports, battery life, weight, and full description"
}

// Output (sample)
{
  "data": {
    "id": "1",
    "name": "HP 15.6\" Laptop, Intel Core i5-1235U, 8GB RAM, 256GB SSD",
    "price": "$499.00",
    "rating": "4.3",
    "reviews_count": "1,247",
    "specifications": {
      "processor": "Intel Core i5-1235U (12th Gen)",
      "ram": "8GB DDR4",
      "storage": "256GB PCIe NVMe SSD",
      "display": "15.6\" FHD (1920 x 1080) Anti-Glare",
      "graphics": "Intel Iris Xe Graphics",
      "battery": "Up to 8 hours",
      "weight": "3.75 lbs",
      "operating_system": "Windows 11 Home"
    },
    "description": "Stay productive and entertained with this HP laptop...",
    "features": [
      "Fast processor for multitasking",
      "Full HD display",
      "Long battery life"
    ]
  }
}
```

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

### Scrape Result

Source: https://docs.mrscraper.com/docs/guides/complex-website/lecho

Example JSON output structure returned by the scraper.

```json
{
  "data": {
    "canonicalUrl": "https://www.lecho.be/economie-politique/belgique/federal/le-plan-de-l-arizona-pour-remettre-100-000-malades-de-longue-duree-a-l-emploi/10637620.html",
    "title": "Le plan de l'Arizona pour remettre 100.000 malades de longue durée à l'emploi",
```

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

### POST /api/shopee/sync/demo

Source: https://docs.mrscraper.com/docs/api/ecommerce/shopee/scraper

Scrapes product details from a specific Shopee URL. Requires an authorization token provided by the service.

```APIDOC
## POST /api/shopee/sync/demo

### Description
This endpoint allows you to scrape product data from a Shopee URL. Use the Scraper Production Server (https://scraper.mrscraper.com) host when calling this endpoint.

### Method
POST

### Endpoint
/api/shopee/sync/demo

### Parameters
#### Request Body
- **url** (string) - Required - Shopee product URL with shop_id and item_id

### Request Example
{
  "url": "https://shopee.tw/product-i.1039910752.21786058727"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **message** (string) - Status message
- **data** (object) - The scraped product data

#### Response Example
{
  "success": true,
  "message": "Successfully scraped",
  "data": {
    "item": {
      "item_id": 21786058727,
      "title": "原廠保固 chicco-多功能食物調理機..."
    }
  }
}
```

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

### GET /api/v1/results

Source: https://docs.mrscraper.com/docs/api/pagination

Retrieves a paginated list of results from the MrScraper API.

```APIDOC
## GET /api/v1/results

### Description
Retrieves a paginated list of scraper results. Supports sorting, searching, and date range filtering.

### Method
GET

### Endpoint
/api/v1/results

### Parameters
#### Query Parameters
- **page** (number) - Required - The page number to retrieve (1-indexed)
- **pageSize** (number) - Required - Number of items per page
- **sortField** (string) - Required - Field name to sort by
- **sortOrder** (string) - Required - Sort direction (ASC or DESC)
- **search** (string) - Optional - Search across all entity columns
- **dateRangeColumn** (string) - Optional - Column name for date filtering
- **startAt** (string) - Optional - Start date for filtering (ISO 8601)
- **endAt** (string) - Optional - End date for filtering (ISO 8601)

### Request Example
curl -X GET "https://api.app.mrscraper.com/api/v1/results?page=1&pageSize=10&sortField=updatedAt&sortOrder=DESC" -H "x-api-token: MRSCRAPER_API_TOKEN" -H "accept: application/json"

### Response
#### Success Response (200)
- **message** (string) - Status message
- **data** (array) - List of result objects
- **meta** (object) - Pagination metadata containing page, pageSize, total, and totalPage
```

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

### Get Result by ID

Source: https://docs.mrscraper.com/docs/integrations/node

Fetches a single scraping result by its unique identifier.

```javascript
import { getResultById } from "@mrscraper/sdk";

const result = await getResultById({
  resultId: "your-result-id",
  // token: "optional_override_token"
});
```

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

### Load Tools with Convenience Function

Source: https://docs.mrscraper.com/docs/integrations/langchain

Use the convenience loader function to retrieve available tools.

```python
from langchain_mrscraper import load_mrscraper_tools

tools = load_mrscraper_tools()
```

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

### Configure Environment Variables

Source: https://docs.mrscraper.com/docs/getting-started/cli

Define API credentials in a .env file for automatic loading by the CLI.

```text
MRSCRAPER_API_KEY=your_api_key_here
```

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

### Load Specific Tools

Source: https://docs.mrscraper.com/docs/integrations/langchain

Initialize only a subset of tools by providing a list of tool names to the loader.

```python
from langchain_mrscraper import load_mrscraper_tools

tools = load_mrscraper_tools(
    token="MRSCRAPER_API_TOKEN",
    tool_names=[
        "mrscraper_fetch_html",
        "mrscraper_get_result_by_id",
    ],
)
```

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

### Authenticate with CLI

Source: https://docs.mrscraper.com/docs/getting-started/cli

Perform one-time authentication per machine or configure via environment variables for CI/CD pipelines.

```bash
mrscraper login
```