From b01fbb38f5fbbe92ccde303863b894bbcf6206be Mon Sep 17 00:00:00 2001
From: kostas-jakeliunas-sb <kostas.jakeliunas@scrapingbee.com>
Date: Tue, 30 Jun 2026 15:26:34 +0300
Subject: [PATCH] [SCR-383] Document Auto-Mode (mode=auto) support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Auto-Mode is a server-side, flag-gated beta feature. The SDK is a pure
pass-through, so `params={'mode': 'auto', 'max_cost': N}` already works
and the `Spb-auto-cost` response header is readable today — no client
code or validation changes are needed (server enforces the 400s).

- README.md: add an "Auto-Mode" example (enable mode=auto, optional
  max_cost cap, read the Spb-auto-cost header) plus usage notes
  (GET only; max_cost optional/>=1; not combinable with
  render_js/premium_proxy/stealth_proxy).
- CHANGELOG.md: add 2.0.3 entry documenting Auto-Mode support.
- scrapingbee/__version__.py: bump 2.0.2 -> 2.0.3.
- tests/test_utils.py: update User-Agent assertion to track the
  bumped version (derived from __version__).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md               |  6 ++++++
 README.md                  | 30 ++++++++++++++++++++++++++++++
 scrapingbee/__version__.py |  2 +-
 tests/test_utils.py        |  2 +-
 4 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c031bcc..78f55e9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.0.3](https://github.com/ScrapingBee/scrapingbee-python/compare/v2.0.2...v2.0.3) (2026-06-30)
+
+### 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.0.0](https://github.com/ScrapingBee/scrapingbee-python/compare/v1.2.0...v2.0.0) (2023-10-03)
 
 ### Improvement
diff --git a/README.md b/README.md
index 328dc4d..4ed1691 100644
--- a/README.md
+++ b/README.md
@@ -95,6 +95,36 @@ You can find all the supported parameters on [ScrapingBee's documentation](https
 
 You can send custom cookies and headers like you would normally do with the requests library.
 
+## 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.get(
+    'https://example.com',
+    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`.
+
 ## Screenshot
 
 Here a little exemple on how to retrieve and store a screenshot from the ScrapingBee blog in its mobile resolution.
diff --git a/scrapingbee/__version__.py b/scrapingbee/__version__.py
index 0309ae2..5fa9130 100644
--- a/scrapingbee/__version__.py
+++ b/scrapingbee/__version__.py
@@ -1 +1 @@
-__version__ = "2.0.2"
+__version__ = "2.0.3"
diff --git a/tests/test_utils.py b/tests/test_utils.py
index 583e497..4b96807 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -18,7 +18,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.0.2",
+        "User-Agent": "ScrapingBee-Python/2.0.3",
         "Spb-Accept-Language": "En-US",
     }