[SCR-383] Document Auto-Mode (mode=auto) support

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.1.1](https://github.com/ScrapingBee/scrapingbee-python/compare/v2.1.0...v2.1.1) (2026-08-06)
+
+### Improvement
+
+- Document Auto-Mode (`mode=auto`) support: ScrapingBee picks the cheapest scraping configuration that succeeds and charges only for the winning one. Read the credits charged from the `Spb-auto-cost` response header, and optionally cap the cost with `max_cost`. No client changes are required — these are pass-through query parameters.
+
 ## [2.1.0](https://github.com/ScrapingBee/scrapingbee-python/compare/v2.0.2...v2.1.0) (2026-07-20)
 
 ### Features

README.md

@@ -23,6 +23,7 @@ Signup to ScrapingBee to [get your API key](https://app.scrapingbee.com/account/
 ## Table of Contents
 
 - [HTML API](#html-api)
+  - [Auto-Mode](#auto-mode)
 - [Google Search API](#google-search-api)
 - [Fast Search API](#fast-search-api)
 - [Amazon API](#amazon-api)
@@ -67,6 +68,37 @@ response = client.html_api(
 )
 ```
 
+### Auto-Mode
+
+With Auto-Mode, ScrapingBee picks the cheapest scraping configuration that successfully scrapes the page for you: it tries the cheaper options first and stops at the first one that works. You are charged only for the winning configuration (and 0 credits if every configuration fails).
+
+```python
+>>> from scrapingbee import ScrapingBeeClient
+
+>>> client = ScrapingBeeClient(api_key='REPLACE-WITH-YOUR-API-KEY')
+
+# Auto-Mode: ScrapingBee picks the cheapest config that works; you're charged only for the winning one.
+>>> response = client.html_api(
+    'https://example.com',
+    method='GET',
+    params={
+        'mode': 'auto',
+        # Optional: cap the credits a single request may cost (omit for uncapped).
+        'max_cost': 25
+    }
+)
+
+# Spb-auto-cost reports the credits actually charged (0 if every config failed).
+>>> response.headers['Spb-auto-cost']
+'1'
+```
+
+Notes:
+
+- Auto-Mode is only available on `GET` requests.
+- `max_cost` is optional and must be `>= 1`; omit it to leave the cost uncapped.
+- `mode=auto` cannot be combined with `render_js`, `premium_proxy`, or `stealth_proxy` (ScrapingBee chooses these for you). Sending them together returns a `400`.
+
 ---
 
 ## Google Search API

scrapingbee/__version__.py

@@ -1 +1 @@
-__version__ = "2.1.0"
+__version__ = "2.1.1"

tests/test_utils.py

@@ -17,7 +17,7 @@ def test_process_headers():
     """It should add a Spb- prefix to header names"""
     output = process_headers({"Accept-Language": "En-US"})
     assert output == {
-        "User-Agent": "ScrapingBee-Python/2.1.0",
+        "User-Agent": "ScrapingBee-Python/2.1.1",
         "Spb-Accept-Language": "En-US",
     }