proxy-scraper-cli 1.28.0__tar.gz → 1.30.0__tar.gz

{proxy_scraper_cli-1.28.0 → proxy_scraper_cli-1.30.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: proxy-scraper-cli
-Version: 1.28.0
-Summary: Finds free HTTP, SOCKS4 and SOCKS5 proxies that actually work: 700+ sources, real checks, honeypot filtering and a rotating local proxy server.
+Version: 1.30.0
+Summary: Finds and checks free HTTP, SOCKS4 and SOCKS5 proxies and shows what each check found: passed, failed or not run, and when. With a rotating local proxy server.
 Author: Maximilian Feix
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/maximilianfeix/proxy-scraper
@@ -39,15 +39,15 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: hypothesis; extra == "dev"
 Requires-Dist: pyyaml; extra == "dev"
 Requires-Dist: markdown-it-py; extra == "dev"
-Requires-Dist: ruff==0.16.10; extra == "dev"
+Requires-Dist: ruff==0.17.0; extra == "dev"
 Dynamic: license-file
 
 <div align="center">
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/banner-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/banner-light.svg">
-  <img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/banner-dark.svg" alt="proxy-scraper – free proxies that actually work" width="100%">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/banner-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/banner-light.svg">
+  <img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/banner-dark.svg" alt="proxy-scraper – free proxies that actually work" width="100%">
 </picture>
 
 [![tests](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/tests.yml/badge.svg)](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/tests.yml)
@@ -55,18 +55,18 @@ Dynamic: license-file
 [![Live proxies](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmaximilianfeix%2Fproxy-scraper%2Fproxy-list%2Fbadges%2Ftotal.json&style=flat-square&labelColor=121113)](#live-list)
 [![PyPI](https://img.shields.io/pypi/v/proxy-scraper-cli?style=flat-square&color=D4F77A&labelColor=121113&label=pypi)](https://pypi.org/project/proxy-scraper-cli/)
 [![Downloads](https://img.shields.io/pepy/dt/proxy-scraper-cli?style=flat-square&color=D4F77A&labelColor=121113&label=downloads)](https://pepy.tech/projects/proxy-scraper-cli)
-[![Python](https://img.shields.io/badge/python-3.9–3.14-D4F77A?style=flat-square&labelColor=121113)](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.9–3.14-D4F77A?style=flat-square&labelColor=121113)](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/pyproject.toml)
 [![Stars](https://img.shields.io/github/stars/maximilianfeix/proxy-scraper?style=flat-square&color=D4F77A&labelColor=121113)](https://github.com/maximilianfeix/proxy-scraper/stargazers)
-[![License](https://img.shields.io/badge/license-MIT-D4F77A?style=flat-square&labelColor=121113)](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-D4F77A?style=flat-square&labelColor=121113)](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/LICENSE)
 
 <a href="https://maximilianfeix.github.io/proxy-scraper/"><img src="https://img.shields.io/badge/Browse_the_live_list-D4F77A?style=for-the-badge&labelColor=121113" alt="Browse the live list"></a>
 <a href="https://github.com/maximilianfeix/free-proxy-list"><img src="https://img.shields.io/badge/Just_the_lists-121113?style=for-the-badge" alt="Just the lists: free-proxy-list"></a>
 <a href="#install"><img src="https://img.shields.io/badge/Install-121113?style=for-the-badge" alt="Install"></a>
 <a href="#from-python"><img src="https://img.shields.io/badge/Python_API-121113?style=for-the-badge" alt="Python API"></a>
 <a href="#mcp"><img src="https://img.shields.io/badge/MCP_server-121113?style=for-the-badge" alt="MCP server for AI agents"></a>
-<a href="https://github.com/maximilianfeix/proxy-scraper/tree/v1.28.0/bot/"><img src="https://img.shields.io/badge/Discord_bot-121113?style=for-the-badge" alt="Discord bot"></a>
+<a href="https://github.com/maximilianfeix/proxy-scraper/tree/v1.30.0/bot/"><img src="https://img.shields.io/badge/Discord_bot-121113?style=for-the-badge" alt="Discord bot"></a>
 
-**English** · [简体中文](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/README.zh-CN.md) · [Español](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/README.es.md) · [Deutsch](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/README.de.md) · [Русский](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/README.ru.md) · [Português (Brasil)](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/README.pt-BR.md) · [Français](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/README.fr.md)
+**English** · [简体中文](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/README.zh-CN.md) · [Español](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/README.es.md) · [Deutsch](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/README.de.md) · [Русский](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/README.ru.md) · [Português (Brasil)](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/README.pt-BR.md) · [Français](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/README.fr.md)
 
 [Install](#install) · [Live list](#live-list) · [For AI agents](#mcp) · [Proxy server](#proxy-server) · [How it works](#how-it-works) · [Recipes](#recipes) · [Options](#options) · [FAQ](#faq)
 
@@ -74,30 +74,46 @@ Dynamic: license-file
 
 ---
 
-Most free proxy lists are 95 % dead, and a good part of the rest are honeypots or proxies that inject scripts into your pages. **proxy-scraper** collects public HTTP, SOCKS4 and SOCKS5 proxies from 700+ sources and keeps only the ones that pass every check. It learns with every run which sources are worth it, and it can turn the result into a single rotating proxy.
+**Proxy checks you can inspect: what passed, what failed, and when.** proxy-scraper collects public HTTP, SOCKS4 and SOCKS5 proxies from hundreds of lists, runs up to four checks on each one and keeps the outcome of each check for the proxies it lists (for the rest it counts how each check ended), so "working" is something you can look at instead of a label you have to trust.
 
-**In numbers:** in one day it ran 3.6 million checks on free proxies – 1.1 % passed, and more than half of the ones that answered failed a second request. [What's actually out there →](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/docs/free-proxies-in-numbers.md)
+https://github.com/user-attachments/assets/b99c1d8f-5bce-4a52-a8a9-b9c2c726301b
 
-**Used by:** the hourly list is a built-in source of [monosans/proxy-scraper-checker](https://github.com/monosans/proxy-scraper-checker) and [gfpcom/free-proxy-list](https://github.com/gfpcom/free-proxy-list).
+<sub>21 seconds · real interface, example numbers, documentation IPs · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/video/proxy-scraper.mp4">mp4</a></sub>
 
-**Try it – no install, about five seconds:**
+**Try it** – no install needed, `uvx` comes with [uv](https://docs.astral.sh/uv/) (`pipx run` does the same):
 
 ```bash
-uvx proxy-scraper-cli --pick 5 --types socks5     # 5 checked proxies
-
-# or just the plain list
-curl -s https://maximilianfeix.github.io/proxy-scraper/socks5.txt | head
+uvx proxy-scraper-cli --pick 3 --verify               # up to 3 proxies from the hourly list that pass right now, from your network
+uvx proxy-scraper-cli --diagnose socks5://HOST:PORT   # one proxy, check by check: what it did and what it didn't
 ```
 
-`uvx` comes with [uv](https://docs.astral.sh/uv/); `pipx run proxy-scraper-cli --pick 5` does the same.
-
-**Only want proxies?** The lists, rebuilt every hour, best first: [all.txt](https://maximilianfeix.github.io/proxy-scraper/all.txt) · [http.txt](https://maximilianfeix.github.io/proxy-scraper/http.txt) · [socks4.txt](https://maximilianfeix.github.io/proxy-scraper/socks4.txt) · [socks5.txt](https://maximilianfeix.github.io/proxy-scraper/socks5.txt) · [proxies.json](https://maximilianfeix.github.io/proxy-scraper/proxies.json) · [by country](https://maximilianfeix.github.io/proxy-scraper/) · [more formats](#live-list)
-
 <div align="center">
-<img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/demo.svg" alt="Animated demo: the live dashboard during a check, the report, the setup wizard and collecting" width="880">
+<img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/demo/checks.gif" alt="Terminal recording: proxy-scraper --pick 2 --verify --https-only prints two proxies and says on stderr why the other four were left out; proxy-scraper --diagnose shows each check of one proxy with its result" width="880">
 </div>
 
-> **Who runs free proxies – and is it safe to use them?** Mostly nobody on purpose: misconfigured servers with an open port, a few deliberately open ones, infected machines, and traps that log or rewrite your traffic. That's why every proxy here has to pass [five checks](#how-it-works), and why they're for public data and testing – never for logins, payments or anything personal. [More on where they come from →](#who-runs-free-proxies)
+<sub>A real terminal recording, made against six simulated proxies on localhost ([reproduce it](https://github.com/maximilianfeix/proxy-scraper/tree/v1.30.0/docs/demo/)). It shows how results are reported. It measures nothing about public proxies.</sub>
+
+The package is `proxy-scraper-cli` on PyPI (the plain name is taken). Once [installed](#install), the command is `proxy-scraper`. `--verify` and `--diagnose` need version 1.30 or newer.
+
+**Three ways to get proxies, and what "checked" means for each:**
+
+| Command | Where the proxies come from | Checked | Takes |
+|---|---|---|---|
+| `proxy-scraper --pick 5` | the [published list](#live-list) | from GitHub's servers when the list was built, about every hour | under a second |
+| `proxy-scraper --pick 5 --verify` | the published list | **now, from your network** | seconds to a minute and a half at most |
+| `proxy-scraper -y` | every list the tool knows | now, from your network | minutes (about three in the hourly runs) |
+
+**What you get**
+
+- **Every check has an outcome you can read.** `passed`, `failed`, `unavailable` or `skipped`, with a reason code, the target and the time, in the terminal, in JSON and from Python. A check that didn't run is never shown as passed, and a check target that is down doesn't turn the proxies checked against it into failures. → [Check states](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/check-states.md)
+- **Fresh when it matters.** `--pick --verify` checks a few proxies from your own network, usually in seconds. `--recheck` does the same for [a list of your own](#examples), and `--diagnose` tells you why one proxy doesn't work.
+- **More than a list.** A [rotating local proxy server](#proxy-server), a [Python API](#from-python), an [MCP server](#mcp) for AI agents, Docker, and exports for curl, proxychains, Clash and sing-box.
+
+**What it can't do.** Free proxies are run by strangers, and of one hour's list only about a quarter is on the list again a day later. A pass is one measurement, from one network, against test targets: it is not a promise for the next hour or for the site you care about. The HTTPS check is a verified TLS connection to one test host, not a security rating. Use free proxies for public data and testing, never for logins, payments or anything personal. → [What the numbers show and what they don't](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/free-proxies-in-numbers.md) · [How it compares](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/comparison.md) · [Who runs free proxies](#who-runs-free-proxies)
+
+**Only want the lists?** You don't need this tool: [free-proxy-list](https://github.com/maximilianfeix/free-proxy-list) has them as plain files per protocol and country, rebuilt about every hour. Or straight from here: [all.txt](https://maximilianfeix.github.io/proxy-scraper/all.txt) · [http.txt](https://maximilianfeix.github.io/proxy-scraper/http.txt) · [socks4.txt](https://maximilianfeix.github.io/proxy-scraper/socks4.txt) · [socks5.txt](https://maximilianfeix.github.io/proxy-scraper/socks5.txt) · [proxies.json](https://maximilianfeix.github.io/proxy-scraper/proxies.json) · [more formats](#live-list)
+
+**Used by:** the hourly list is a built-in source of [monosans/proxy-scraper-checker](https://github.com/monosans/proxy-scraper-checker) and [gfpcom/free-proxy-list](https://github.com/gfpcom/free-proxy-list).
 
 <details>
 <summary><b>Table of contents</b></summary>
@@ -166,7 +182,7 @@ pip install -r requirements.txt
 python3 proxy_scraper.py
 ```
 
-Every [release](https://github.com/maximilianfeix/proxy-scraper/releases/latest) also ships a wheel you can install with `pip install <file>.whl`, and a multi-arch image (amd64/arm64) on `ghcr.io`. In the container the wizard never shows up, it runs straight away. For the proxy server use `--serve --serve-host 0.0.0.0` with `-p 127.0.0.1:8899:8899`, so the port is only open on your own machine.
+Every [release](https://github.com/maximilianfeix/proxy-scraper/releases/latest) also ships a wheel you can install with `pip install <file>.whl`, and a multi-arch image (amd64/arm64) on `ghcr.io`. In the container the wizard never shows up, it runs straight away. For the proxy server use `--serve --serve-host 0.0.0.0 --serve-open` with `-p 127.0.0.1:8899:8899`, so the port is only open on your own machine – or set `-e PROXY_SCRAPER_SERVE_PASSWORD=…` instead of `--serve-open`.
 
 Tab completion for bash, zsh, fish and PowerShell:
 
@@ -183,7 +199,8 @@ Installed, the learned state lives in your user data folder (`~/Library/Applicat
 Started without arguments, a wizard asks what you are looking for:
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/wizard.svg" alt="Setup wizard" width="760">
+<img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/wizard.svg" alt="Setup wizard" width="760">
+<sub>Illustration: the real interface, rendered with sample data by <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/make_demo.py">docs/make_demo.py</a>. The numbers in it are made up.</sub>
 </div>
 
 | Preset | What it does |
@@ -204,7 +221,7 @@ Keys: <kbd>↑</kbd><kbd>↓</kbd> select · <kbd>Space</kbd> toggle · <kbd>1</
 
 ## Live proxy list
 
-Don't want to scan yourself? Every hour **GitHub Actions** runs the tool and publishes the hits to the [`proxy-list`](https://github.com/maximilianfeix/proxy-scraper/tree/proxy-list) branch – every entry worked in the last run, best first: fast ones that are likely to still be up come on top.
+Don't want to scan yourself? About every hour **GitHub Actions** runs the tool and publishes the hits to the [`proxy-list`](https://github.com/maximilianfeix/proxy-scraper/tree/proxy-list) branch – every entry passed the first request, the second request and the content check in the last run (the HTTPS test is recorded per entry, not required), best first: fast ones that are likely to still be up come on top.
 
 > **Just want the lists?** They also live in a repository of their own, **[maximilianfeix/free-proxy-list](https://github.com/maximilianfeix/free-proxy-list)** – one list per protocol, per country and per site, updated every hour, with the numbers of the last run on the front page. Watch or star it to keep it at hand. Other tools pull it too: [monosans/proxy-scraper-checker](https://github.com/monosans/proxy-scraper-checker) and [gfpcom/free-proxy-list](https://github.com/gfpcom/free-proxy-list) use it as a built-in source.
 
@@ -214,11 +231,11 @@ Don't want to scan yourself? Every hour **GitHub Actions** runs the tool and pub
   <img src="https://maximilianfeix.github.io/proxy-scraper/chart-dark.svg" alt="Working proxies over the last days, stacked by protocol – redrawn with every run" width="100%">
 </picture></a>
 
-**→ [Browse it on the website](https://maximilianfeix.github.io/proxy-scraper/)** – search, filter by type, country, HTTPS, provider and latency, see how long each proxy has been up and how often it was on the list this week, copy or download exactly the proxies you need.
+**→ [Browse it on the website](https://maximilianfeix.github.io/proxy-scraper/)** – search, filter by type, country, HTTPS, provider and latency, see how long each proxy has been on the list and in how many of the week's runs, copy or download exactly the proxies you need.
 
 Every protocol and country also has its own page with a plain download, e.g. [SOCKS5](https://maximilianfeix.github.io/proxy-scraper/socks5/) or [Germany](https://maximilianfeix.github.io/proxy-scraper/country/de/) (`country/de/proxies.txt`).
 
-<div align="center"><a href="https://maximilianfeix.github.io/proxy-scraper/"><img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/website.png" alt="The live list website" width="860"></a></div>
+<div align="center"><a href="https://maximilianfeix.github.io/proxy-scraper/"><img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/website.png" alt="The live list website" width="860"></a></div>
 
 <div align="center">
 
@@ -236,7 +253,7 @@ Every protocol and country also has its own page with a plain download, e.g. [SO
 | HTTP · SOCKS4 · SOCKS5 | `1.2.3.4:8080` | [http.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/http.txt) · [socks4.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/socks4.txt) · [socks5.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/socks5.txt) |
 | HTTPS-capable only | `type://ip:port` | [https.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/https.txt) |
 | Elite only | `type://ip:port` | [elite.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/elite.txt) |
-| Gets through to Google · Reddit · Amazon · Instagram · TikTok · Discord (no captcha, no block in the last run) | `type://ip:port` | [google.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/google.txt) · [reddit.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/reddit.txt) · [amazon.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/amazon.txt) · [instagram.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/instagram.txt) · [tiktok.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/tiktok.txt) · [discord.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/discord.txt) |
+| Gets through to Google · Reddit · Amazon · Instagram · TikTok · Discord (one test request got a normal page in the last run) | `type://ip:port` | [google.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/google.txt) · [reddit.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/reddit.txt) · [amazon.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/amazon.txt) · [instagram.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/instagram.txt) · [tiktok.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/tiktok.txt) · [discord.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/works-with/discord.txt) |
 | Stable, on the list in 90 %+ of this week's runs | `type://ip:port` | [stable.txt](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/stable.txt) |
 | With all details | latency, country, HTTPS, anonymity, exit IP, uptime, sites | [proxies.json](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/proxies.json) · [proxies.csv](https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/proxies.csv) |
 
@@ -250,13 +267,13 @@ Every protocol and country also has its own page with a plain download, e.g. [SO
 curl -s https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/proxy-list/socks5.txt | head
 ```
 
-**Where they come from:** [which free proxy lists actually work](https://maximilianfeix.github.io/proxy-scraper/sources/) ranks all 700+ sources every hour – how many proxies each one lists, how many passed every check and the share. The same as data: [sources.json](https://maximilianfeix.github.io/proxy-scraper/sources.json).
+**Where they come from:** [which free proxy lists actually work](https://maximilianfeix.github.io/proxy-scraper/sources/) ranks every source of the hourly runs – how many proxies each one lists, how many passed every check and the share. The same as data: [sources.json](https://maximilianfeix.github.io/proxy-scraper/sources.json).
 
 **Over time:** every day the first run's `proxies.json` is kept for good as a gzipped asset of the release of that year, like [snapshots-2026](https://github.com/maximilianfeix/proxy-scraper/releases/tag/snapshots-2026) – `proxies-2026-09-28.json.gz` and so on, for anyone who wants to look at free proxies over weeks and months.
 
 Every file is also on GitHub Pages, which sits behind a CDN, isn't rate limited like raw.githubusercontent and sends CORS headers, so it works straight from the browser: `https://maximilianfeix.github.io/proxy-scraper/socks5.txt`. [jsDelivr](https://cdn.jsdelivr.net/gh/maximilianfeix/proxy-scraper@proxy-list/) works too, but can lag behind by a few hours.
 
-Or let the tool start from it: `proxy-scraper --recheck live` downloads the list and checks it again from **your** network – about 30 seconds instead of a full scan (517 of 1,169 worked from here). With `--serve` you have a rotating proxy in under a minute.
+Or let the tool start from it: `proxy-scraper --recheck live` downloads the list and checks it again from **your** network – well under a minute instead of a full scan. How many still work from your network differs a lot from the list's own count, which is the point of checking again. Add `--serve` and the result is a rotating proxy.
 
 <a id="mcp"></a>
 
@@ -270,9 +287,9 @@ Or let the tool start from it: `proxy-scraper --recheck live` downloads the list
 
 | Tool | What it does |
 |---|---|
-| `get_proxies` | working proxies right now, from the hourly list – filter by protocol, country, HTTPS, elite, no datacenter, not blocklisted, stable, uptime, latency, gets through to Google/Reddit/Amazon |
+| `get_proxies` | proxies from the hourly list, as checked in its last run – filter by protocol, country, HTTPS, elite, no datacenter, not blocklisted, stable, uptime, latency, gets through to Google/Reddit/Amazon |
 | `check_proxies` | checks proxies from your own network, so they work from where your code runs (30–90 s, reports progress) |
-| `fetch_url` | loads a page through a verified proxy, switches proxies by itself when one fails, returns readable text – HTTPS only through proxies with verified TLS |
+| `fetch_url` | loads a page through a proxy from the checked list, switches proxies by itself when one fails, returns readable text – HTTPS only through proxies that passed the TLS test |
 
 Things to ask your agent: *"Load bbc.com/news as seen from the UK"*, *"Give me 5 SOCKS5 proxies from Germany that aren't in a datacenter"*, *"Check which of these sites block free proxies"*.
 
@@ -356,7 +373,7 @@ Started without arguments, the tool asks what you need using the arrow keys –
 <td width="50%" valign="top">
 
 **Fast**<br>
-700+ sources fetched in parallel, large lists parsed on all CPU cores, hand-written HTTP/SOCKS handshakes directly on `asyncio` with 2000+ checks at once.
+350+ curated lists, plus the ones found through meta lists and GitHub search (about 750 to 820 in the hourly runs), fetched in parallel. Large lists are parsed on all CPU cores, and hand-written HTTP/SOCKS handshakes run directly on `asyncio`, 2,000 checks at once.
 
 </td>
 </tr>
@@ -364,7 +381,7 @@ Started without arguments, the tool asks what you need using the arrow keys –
 <td valign="top">
 
 **Real verification**<br>
-Every hit has to fetch two independent pages – that weeds out **honeypots** that only answer check requests: over 3.6 million checks, 54 % of the proxies that answered the first request failed the second. A third request catches proxies that **tamper with content**: about one in 40 working proxies changed a known page, usually by injecting a script ([the numbers](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/docs/free-proxies-in-numbers.md)). Plus: HTTPS through a tunnel with **verified TLS**, anonymity level *elite / anonymous / transparent* and the country of the exit IP.
+Every hit has to answer **a second request** to an unrelated site with the same exit IP: over 3.6 million checks, 54 % of the proxies that answered the first request did not pass the second. A third request fetches **a static test page that has to arrive byte for byte**: for 5.2 % of the proxies that got that far it didn't. Why a proxy fails either one (unstable, a rotating exit, a changed or cut-off page) is not something those runs recorded; from 1.30 on every result carries a reason code ([the numbers](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/free-proxies-in-numbers.md), [check states](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/check-states.md)). Plus: HTTPS through a tunnel with **a TLS certificate that verifies** for the test host, anonymity level *elite / anonymous / transparent* and the country of the exit IP.
 
 </td>
 <td valign="top">
@@ -384,7 +401,7 @@ Searches GitHub for actively maintained proxy lists and reads source lists maint
 <td valign="top">
 
 **Filters & target sites**<br>
-With `--target google.com` a proxy only counts if it really reaches the site – many public proxies are blocked by Google, Discord & co. Filter by country, HTTPS, anonymity and latency, and stop with `--want 50` as soon as enough matching proxies are found. Filters even speed things up: with `--max-latency 1000` slow proxies are given up after 1 s instead of 8 s.
+With `--target google.com` a proxy only counts if it really reaches the site – many public proxies are turned away by the big sites. Filter by country, HTTPS, anonymity and latency, and stop with `--want 50` as soon as enough matching proxies are found. Filters even speed things up: with `--max-latency 1000` slow proxies are given up after 1 s instead of 8 s.
 
 </td>
 </tr>
@@ -412,7 +429,7 @@ macOS, Linux and Windows, Python 3.9 to 3.14. Only two dependencies: `rich` and
 <td valign="top">
 
 **Thoroughly tested**<br>
-760+ tests run offline against real mini proxies and honeypots on `localhost` – on Linux, macOS and Windows with Python 3.9, 3.11, 3.13 and 3.14.
+1,100+ tests run offline against real mini proxies with known flaws on `localhost` – on Linux, macOS and Windows with Python 3.9, 3.11, 3.13 and 3.14.
 
 </td>
 </tr>
@@ -422,20 +439,23 @@ macOS, Linux and Windows, Python 3.9 to 3.14. Only two dependencies: `rich` and
 
 ### Why not just download a list?
 
-| | Typical proxy list repo | **proxy-scraper** |
-|---|:---:|:---:|
-| Proxies checked right before you use them | ❌ | ✅ |
-| Honeypots that fake a successful check filtered out | ❌ | ✅ |
-| Proxies that inject scripts or ads filtered out | ❌ | ✅ |
-| HTTPS tested with verified TLS | rarely | ✅ |
-| Anonymity level and country per proxy | sometimes | ✅ |
-| Only proxies that reach *your* target site | ❌ | ✅ `--target` |
-| Learns which sources are worth it | ❌ | ✅ |
-| Usable as a single rotating proxy | ❌ | ✅ `--serve` |
-| API to fetch a proxy (proxy_pool compatible) | ❌ | ✅ [`/get`](#pool-api) |
-| Ready-made list without running anything | ✅ | ✅ [live list](#live-list) |
-
-Named and dated: [how it compares to proxifly, TheSpeedX, monosans and clarketm](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/docs/comparison.md).
+A list tells you what worked for its author when it was built. This is what the tool adds; what other projects document about their own checks is in the [comparison](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/comparison.md), no other list was measured for it.
+
+| | **proxy-scraper** |
+|---|---|
+| Checked right before you use them, from your network | `--pick --verify`, `--recheck`, or a scan |
+| The outcome of every check, with reason and time | `checks` in JSON, `--diagnose` |
+| A second request that has to show the same exit IP | always attempted; if its target is down, your own run keeps the proxy as `unavailable`, the hourly list and `--verify` don't |
+| A test page that has to arrive byte for byte | the same |
+| HTTPS tested with a certificate that verifies (one test host) | unless `--fast` |
+| Anonymity level and country per proxy | yes |
+| Only proxies that reach *your* target site | `--target` |
+| Learns which sources are worth it | yes |
+| Usable as a single rotating proxy | `--serve` |
+| API to fetch a proxy (same paths as proxy_pool) | [`/get`](#pool-api) |
+| Ready-made list without running anything | [live list](#live-list) |
+
+Named and dated: [how it compares to other tools and lists, task by task](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/comparison.md).
 
 <a id="examples"></a>
 
@@ -526,7 +546,7 @@ It runs on 127.0.0.1 with a random password, takes over each new hourly list by
 
 ## Rotating proxy server
 
-A list is nice – but usually you just want to enter **one** proxy that always works:
+A list is nice – but usually you just want to enter **one** proxy address and have something behind it that keeps trying:
 
 ```bash
 proxy-scraper --recheck --serve     # recheck the last hits, then go – takes seconds
@@ -551,7 +571,7 @@ proxy-scraper --recheck --serve --serve-host 0.0.0.0
 curl -x "http://country-de:$PROXY_SCRAPER_SERVE_PASSWORD@your-server:8899" https://api.ipify.org
 ```
 
-Without a password, `--serve-host` means **anyone who reaches the port can use it**. The ready-made [`compose.yaml`](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/compose.yaml) starts the server in Docker from the live list, with a password, a health check and learned state in a volume: put `PROXY_PASSWORD=…` into `.env`, then `docker compose up -d`.
+Without a password the server refuses to start on any address but `127.0.0.1`: that would be an open proxy for **anyone who reaches the port** (Docker publishes ports past host firewalls like ufw). If a firewall or `-p 127.0.0.1:…` already keeps others out, say so with `--serve-open`. The ready-made [`compose.yaml`](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/compose.yaml) starts the server in Docker from the live list, with a password, a health check and learned state in a volume: put `PROXY_PASSWORD=…` into `.env`, then `docker compose up -d`.
 
 | Option | What it does |
 |---|---|
@@ -568,11 +588,11 @@ Without a password, `--serve-host` means **anyone who reaches the port can use i
 - `--serve-refill 6` checks fresh proxies every 6 hours in the background (the live list with `--recheck live`, otherwise the last run + history) with the same checks and filters, and adds the hits – a server that runs for days doesn't run dry
 - listens on `127.0.0.1` only (unless `--serve-host` says otherwise), optionally with a password; live view with requests, success rate, pool and the latest connections
 
-In testing: 20 of 20 HTTPS requests succeeded, over 15 different exit IPs. In the wizard this is **Proxy server right away**.
+In the wizard this is **Proxy server right away**.
 
 **Live dashboard:** open `http://127.0.0.1:8899/__proxy-scraper/` in a browser – the pool, success rate, traffic, a live chart of requests, countries, the best proxies and the latest connections, refreshed every two seconds. It needs nothing from the internet, and `--serve-password` protects it like the rest.
 
-<div align="center"><img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/dashboard-live.png" alt="The live dashboard of the rotating proxy server: usable proxies, success rate, requests per second, countries and the latest connections" width="860"></div>
+<div align="center"><img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/dashboard-live.png" alt="The live dashboard of the rotating proxy server: usable proxies, success rate, requests per second, countries and the latest connections" width="860"></div>
 
 <a id="pool-api"></a>
 
@@ -598,7 +618,7 @@ curl "http://127.0.0.1:8899/report?proxy=203.0.113.7:8080&ok=0"  # it failed you
 
 Filters work on `/get`, `/pop` and `/all`: `country=DE,AT`, `protocol=socks5`, `https=1`, `anonymity=elite`, `max_latency=1500`, and `format=txt` for plain URLs. With `--serve-password` the API wants it as Basic auth, like the status page.
 
-**Coming from [jhao104/proxy_pool](https://github.com/jhao104/proxy_pool)?** The endpoints, `type=https` and the JSON fields (`proxy`, `https`, `region`, `anonymous`, `check_count`, `fail_count`, …) are the same, so point your code at port 8899 and it keeps working – without Redis, and with proxies that passed the honeypot, tampering and TLS checks:
+**Coming from [jhao104/proxy_pool](https://github.com/jhao104/proxy_pool)?** The endpoints, `type=https` and most JSON fields (`proxy`, `https`, `region`, `check_count`, `fail_count`, …) are the same, so point your code at port 8899 and most of it keeps working (three differences: there is no `last_time`, `anonymous` is true/false, not a string, and `source` is always `proxy-scraper`) – without Redis, and with proxies that passed the second-request, content and TLS checks:
 
 ```python
 import requests
@@ -610,16 +630,16 @@ requests.get("https://example.com", proxies={"http": proxy, "https": proxy})
 
 ## Discord and Telegram bot
 
-The live list can also come to you: [`bot/`](https://github.com/maximilianfeix/proxy-scraper/tree/v1.28.0/bot/) is a Discord bot that posts every run into a server – a summary with the fastest proxies, the full lists per protocol as files, and slash commands like `/proxies type:socks5 country:DE https:true`. It sets up its own read-only channels when you invite it, and a GitHub Action deploys it to a server as a systemd service. The same process answers on Telegram too: `/proxy de socks5` for one proxy with a curl line, `/proxies 10 us https` for a short list. Setup in [bot/README.md](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/bot/README.md).
+The live list can also come to you: [`bot/`](https://github.com/maximilianfeix/proxy-scraper/tree/v1.30.0/bot/) is a Discord bot that posts every run into a server – a summary with the fastest proxies, the full lists per protocol as files, and slash commands like `/proxies type:socks5 country:DE https:true`. It sets up its own read-only channels when you invite it, and a GitHub Action deploys it to a server as a systemd service. The same process answers on Telegram too: `/proxy de socks5` for one proxy with a curl line, `/proxies 10 us https` for a short list. Setup in [bot/README.md](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/bot/README.md).
 
 <a id="how-it-works"></a>
 
 ## How it works
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/checks-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/checks-light.svg">
-  <img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/checks-dark.svg" alt="The five checks: 700+ lists, a real handshake, two sites with one IP, nothing injected, the details" width="100%">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/checks-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/checks-light.svg">
+  <img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/checks-dark.svg" alt="Illustration of the steps: the lists, a real handshake, two sites with one exit IP, an unchanged test page, the details" width="100%">
 </picture>
 
 
@@ -634,28 +654,29 @@ flowchart LR
     G -. next run .-> C
 ```
 
-1. **Sources** – the curated list in [`sources.json`](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/proxyscraper/sources.json), meta sources (other projects that maintain lists of proxy sources) and, once a day, a GitHub search for actively maintained repos. Every search adds to what earlier ones found; a list the search hasn't seen for three weeks drops out.
-2. **Collect** – plain text, HTML tables, JSON APIs and `type://ip:port` lines are recognized; private and reserved address ranges are dropped. Lists that haven't changed since the last run answer `304` and come from a local cache – a second run right after the first loads 0 MB instead of ~160 MB.
+1. **Sources** – the curated list in [`sources.json`](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/proxyscraper/sources.json), meta sources (other projects that maintain lists of proxy sources) and, once a day, a GitHub search for actively maintained repos. Every search adds to what earlier ones found; a list the search hasn't seen for three weeks drops out.
+2. **Collect** – plain text, HTML tables, JSON APIs and `type://ip:port` lines are recognized; private and reserved address ranges are dropped. Lists that haven't changed since the last run answer `304` and come from a local cache – a second run right after the first loads only what changed (in one logged hourly run 52 MB, with 431 of 746 lists unchanged).
 3. **Prioritize** – known working proxies first, then by the learned hit rate of their sources.
-4. **Check** – every proxy has to fetch its exit IP from a check target (`checkip.amazonaws.com`, with `ifconfig.me`, `ipinfo.io`, `wtfismyip.com` and `ident.me` as reserves – none of them behind Cloudflare) and return a valid, *foreign* IP. If the target goes down mid-run, the tool switches and re-checks the proxies that were affected, so the statistics don't learn from an outage. Anyone passing your own IP through is out. Then comes the **confirmation** via `httpbin.org`: fake proxies that only answer the first check with “200 + IP” fail here. Finally a static HTML page has to arrive byte for byte as it does without a proxy – anyone injecting ads or scripts is out.
-5. **Countries and providers** – looked up offline in the free DB-IP databases, including the provider (ASN) and whether it's probably a datacenter (about 45 % of working proxies are) (downloaded once a month, ~2 µs per lookup); ip-api.com is only asked for the few addresses it doesn't know.
-6. **Blocklists** – one DNS lookup per exit IP against SpamCop, cached for the run: about 29 % of working proxies exit from a listed IP, and sites that use the list show those captchas or block them. `--no-blocklisted` drops them. If your DNS resolver is refused by SpamCop (large public resolvers are), the lookup is skipped instead of guessing.
+4. **Check** – every proxy has to fetch its exit IP from a check target (`checkip.amazonaws.com`, with `ifconfig.me`, `ipinfo.io`, `wtfismyip.com` and `ident.me` as reserves – none of them behind Cloudflare) and return a valid, *foreign* IP. If the target goes down mid-run, the tool switches and re-checks the proxies that were affected, so the statistics don't learn from an outage. The targets of the later checks are asked directly when a check against them fails; if they don't answer either, the proxy's check is `unavailable`, not `failed`. Anyone passing your own IP through is out. Then comes the **second request** via `httpbin.org`, which has to see the same exit IP: proxies that only answer the first check with “200 + IP” fail here, and so do unstable ones and exits that rotate. Finally a static HTML page has to arrive byte for byte as it does without a proxy. Each of these leaves [its outcome](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/check-states.md) on the result.
+5. **Countries and providers** – looked up offline in the free DB-IP databases, including the provider (ASN) and whether the provider's name looks like a hosting company (between 45 % and 65 % of the entries in the lists we looked at) (downloaded once a month, ~2 µs per lookup); ip-api.com is only asked for the few addresses it doesn't know.
+6. **Blocklists** – one DNS lookup per exit IP against SpamCop, cached for the run: between 28 % and 43 % of the entries exited from a listed IP in the lists we looked at, and sites that use the list show those captchas or block them. `--no-blocklisted` drops them. If your DNS resolver is refused by SpamCop (large public resolvers are), the lookup is skipped instead of guessing.
 7. **Learn** – hit rates and history are stored. Sources without hits, with content unchanged for a week or permanently unreachable are skipped.
 
 <details>
 <summary><b>📸 See the live dashboard and final report</b></summary>
 <br>
 <div align="center">
-<img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/dashboard.svg" alt="Live dashboard while checking" width="860">
+<img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/dashboard.svg" alt="Live dashboard while checking" width="860">
 <br><br>
-<img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.28.0/docs/summary.svg" alt="Final report after a run" width="860">
+<img src="https://raw.githubusercontent.com/maximilianfeix/proxy-scraper/v1.30.0/docs/summary.svg" alt="Final report after a run" width="860">
+<sub>Illustration: the real interface, rendered with sample data by <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/make_demo.py">docs/make_demo.py</a>. The numbers in it are made up.</sub>
 </div>
 </details>
 
 ### Your own lists
 
 ```bash
-proxy-scraper --source https://example.com/my-list.txt --source socks5=./socks.txt   # on top of the 700+ sources
+proxy-scraper --source https://example.com/my-list.txt --source socks5=./socks.txt   # on top of the built-in sources
 proxy-scraper --only-sources --source bought.txt --want 50                            # only yours
 ```
 
@@ -856,7 +877,7 @@ pip download requests   # git, pip, npm & co. now go through the pool
 
 **In a GitHub workflow** – the action picks working proxies for the next steps
 
-[Marketplace](https://github.com/marketplace/actions/proxy-scraper-free-working-proxies) · [Complete workflow, inputs and outputs](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/docs/github-action.md)
+[Marketplace](https://github.com/marketplace/actions/proxy-scraper-free-working-proxies) · [Complete workflow, inputs and outputs](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/github-action.md)
 
 ```yaml
 - id: proxies
@@ -929,8 +950,12 @@ curl.exe -x (Get-Content "$run\all.txt" -TotalCount 1) http://api.ipify.org
 | `--no-cache` | download every list again (unchanged ones are normally skipped via ETag) |
 | `--list-sources [N]` | show the source ranking (add `--json` for scripts: url, status, hit rate, checks, last change) |
 | `--pick [N]` | print N proxies (default 1) from the hourly checked list and exit – no scan, same filters, plus `--min-uptime PERCENT`, `--min-speed KBPS` and `--works-on google,reddit,…` |
-| `--serve-host ADDR` | where the proxy server listens (default `127.0.0.1`; `0.0.0.0` for Docker, with a warning) |
+| `--verify` | with `--pick`: check the candidates from your machine first and print only those that pass now – 5 candidates per proxy asked for (10 to 60), up to 8 at a time, 90 s at most; exit code 3 if fewer than N passed |
+| `--diagnose PROXY` | check one proxy and show what each check found, [state by state](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/check-states.md); exit code 0 nothing failed, 1 a check failed, 3 a check could not run |
+| `--json` | with `--pick` or `--diagnose` (and `--list-sources`): the result as JSON on stdout |
+| `--serve-host ADDR` | where the proxy server listens (default `127.0.0.1`; any other address needs a password or `--serve-open`) |
 | `--serve-password SECRET` | clients must send this password in the proxy login; better set `PROXY_SCRAPER_SERVE_PASSWORD` |
+| `--serve-open` | allow `--serve-host` without a password – only behind a firewall or with `docker -p 127.0.0.1:…` |
 | `--rotate STRATEGY` · `--sticky SEC` | how the proxy server picks proxies, see [above](#proxy-server) |
 | `--serve-refill HOURS` | while serving, check fresh proxies every HOURS and add the hits to the pool |
 | `--serve [PORT]` | afterwards serve as a rotating proxy on `127.0.0.1:PORT` (default: 8899) |
@@ -954,10 +979,10 @@ The repo does part of the work itself:
 
 | Workflow | What it does |
 |---|---|
-| [**tests**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/tests.yml) | 3 operating systems × 3 Python versions, plus a built and installed package – on every push and pull request |
+| [**tests**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/tests.yml) | 3 operating systems × 4 Python versions, plus a built and installed package – on every push and pull request |
 | [**lint**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/lint.yml) | `ruff` with a pinned version – same rules locally and in CI |
 | [**codeql**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/codeql.yml) | security analysis on every push and once a week |
-| [**proxy list**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/proxy-list.yml) | every hour: collect, check, publish to `proxy-list`. The learned statistics live in the Actions cache, so the tool keeps getting better in the cloud too |
+| [**proxy list**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/proxy-list.yml) | about every hour: collect, check, publish to `proxy-list`. The learned statistics live in the Actions cache, so the tool keeps getting better in the cloud too |
 | [**docker**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/docker.yml) | builds the image on every change and runs a real scan inside it; on a version tag it publishes `linux/amd64` + `linux/arm64` to `ghcr.io` |
 | [**release**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/release.yml) | on a version tag: test, build, smoke-test and publish a GitHub release with the wheel |
 | [**discord bot**](https://github.com/maximilianfeix/proxy-scraper/actions/workflows/bot.yml) | tests the bot and deploys it to the server on every change in `bot/` |
@@ -980,7 +1005,9 @@ Almost nobody runs a free proxy for you. What ends up on public lists is usually
 - **Infected machines** – computers and IoT devices whose owners don't know they relay traffic. Many residential exits are like this.
 - **Traps** – honeypots that log what goes through them, and proxies that rewrite pages to inject ads or scripts.
 
-proxy-scraper can't tell an infected home router from an open office proxy, but it filters what it can measure: a proxy has to answer two independent requests with the same exit IP (honeypots that only answer scanners drop out), deliver a known page byte for byte (injectors drop out), and HTTPS counts only with a certificate that verifies end to end. Each hit says whether its exit is in a datacenter.
+That is general background, not something this project measured: a check can't see who runs a proxy or why.
+
+proxy-scraper can't tell an infected home router from an open office proxy, but it filters what it can measure: a proxy has to answer two independent requests with the same exit IP, deliver a known page byte for byte, and HTTPS counts only with a certificate that verifies for the test host. Each hit says whether its exit is in a datacenter.
 
 Good uses: public data, checking how a site looks from another country, testing your own blocking and rate limits, research. Never send passwords, cookies, payment or personal data through a free proxy, and keep HTTPS certificate checks on. Use them only where you're allowed to.
 
@@ -1006,7 +1033,7 @@ Yes, in PowerShell and Windows Terminal. `uvloop` doesn't exist there and is ski
 <summary><b>Why does it find fewer proxies than other lists claim to have?</b></summary>
 <br>
 
-Because only proxies that pass every check are kept. Many lists count anything that accepts a TCP connection; here a proxy must fetch two independent pages and show a foreign IP. That's usually a few hundred out of a million candidates – but they work.
+Because only proxies that pass every check are kept: two independent requests that show the same foreign exit IP, and a test page that arrives unchanged. In the hourly runs that is about 1 % of the 150,000 candidates checked. They passed from the network that checked them, at that moment.
 
 </details>
 
@@ -1022,7 +1049,7 @@ Lines like `socks5://user:pass@1.2.3.4:1080` keep their login: HTTP proxies get
 <summary><b>How fresh is the live list?</b></summary>
 <br>
 
-It's rebuilt every hour; the “updated” badge shows the last run. Free proxies come and go quickly, so for anything important run `proxy-scraper --recheck` right before use.
+It's rebuilt about every hour; the “updated” badge shows the last run. Free proxies come and go quickly, so for anything important run `proxy-scraper --recheck` right before use.
 
 </details>
 
@@ -1058,7 +1085,7 @@ Shipped in [v1.5](https://github.com/maximilianfeix/proxy-scraper/milestone/5):
 
 ## Contributing
 
-Bug reports, new sources and pull requests are very welcome – see [CONTRIBUTING.md](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/CONTRIBUTING.md), and [docs/ARCHITECTURE.md](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/docs/ARCHITECTURE.md) for how the pieces fit together. The short version:
+Bug reports, new sources and pull requests are very welcome – see [CONTRIBUTING.md](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/CONTRIBUTING.md), and [docs/ARCHITECTURE.md](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/docs/ARCHITECTURE.md) for how the pieces fit together. The short version:
 
 ```bash
 pip install -e ".[dev]"
@@ -1078,7 +1105,7 @@ proxyscraper/
 ├── app.py              one run in phases: network → jobs → check → learn & report
 ├── options.py          RunOptions + Filters – all settings in one place
 ├── pipeline.py         collect sources, prioritize, check loop
-├── checker.py          checks, honeypot confirmation, HTTPS test
+├── checker.py          the checks: basic, second request, content, HTTPS
 ├── handshake.py        HTTP/SOCKS4/SOCKS5 handshakes incl. login
 ├── judges.py           check targets, Cloudflare filter, failover
 ├── sources.py          source lists, meta sources, GitHub discovery, statistics
@@ -1135,7 +1162,7 @@ From the same author: [dejabuilt](https://github.com/maximilianfeix/dejabuilt),
 
 ## Acknowledgements
 
-proxy-scraper stands on the work of the people who publish free proxy lists. Thanks to everyone listed in [`sources.json`](https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/proxyscraper/sources.json), and especially to
+proxy-scraper stands on the work of the people who publish free proxy lists. Thanks to everyone listed in [`sources.json`](https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/proxyscraper/sources.json), and especially to
 
 - [monosans/proxy-scraper-checker](https://github.com/monosans/proxy-scraper-checker) and [gfpcom/free-proxy-list](https://github.com/gfpcom/free-proxy-list), whose curated source collections are read as meta sources
 - [Textualize/rich](https://github.com/Textualize/rich), which draws the whole terminal UI
@@ -1150,7 +1177,7 @@ This tool only collects publicly listed proxies and checks whether they work. Yo
 
 ---
 
-<sub>Made in Germany by <a href="https://github.com/maximilianfeix">@maximilianfeix</a> · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/LICENSE">MIT License</a> · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/CHANGELOG.md">Changelog</a> · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/SECURITY.md">Security</a> · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.28.0/CONTRIBUTING.md">Contributing</a></sub>
+<sub>Made in Germany by <a href="https://github.com/maximilianfeix">@maximilianfeix</a> · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/LICENSE">MIT License</a> · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/CHANGELOG.md">Changelog</a> · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/SECURITY.md">Security</a> · <a href="https://github.com/maximilianfeix/proxy-scraper/blob/v1.30.0/CONTRIBUTING.md">Contributing</a></sub>
 
 <sub>If proxy-scraper saves you time, a ⭐ helps others find it.</sub>