> ## Documentation Index
> Fetch the complete documentation index at: https://verifyngo.chocolatemoo53.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Progressive challenge mode

> Enable progressive mode to let new visitors browse freely for a configurable number of requests before a CAPTCHA challenge appears. 

By default verifyngo challenges every visitor on their first request. Progressive mode takes a lighter approach: it trusts new visitors initially and only shows a CAPTCHA once they have made more than a set number of page requests within a rolling time window. This avoids interrupting visitors who are clearly browsing normally.

## How it works

1. When a visitor hits a path listed in `passive_paths`, verifyngo sets a short-lived passive cookie and proxies the request through to your upstream without a challenge.
2. Each subsequent request to a `passive_paths` route increments a per-visitor counter.
3. Once the counter exceeds `max_requests` within the `request_window`, the next request triggers a real CAPTCHA challenge.
4. After the visitor solves the CAPTCHA, verifyngo issues a full verified cookie and the visitor is never challenged again — until that cookie expires.

Requests to static assets and paths matched by `bypass_paths` do not count toward the passive request budget.

## Configuration

Enable progressive mode by adding a `progressive` block to `config.json`:

```json theme={null}
"progressive": {
  "enabled": true,
  "passive_paths": [
    "^/$",
    "^/blog",
    "^/docs"
  ],
  "passive_ttl": "30m",
  "max_requests": 50,
  "request_window": "10m"
}
```

**enabled** `boolean` (default: false)

Set to `true` to turn on progressive mode.

**passive\_paths** `array of strings`

The URL paths (as regular expressions) that participate in passive request counting. Only requests to matching paths increment the counter and receive a passive cookie. Keep this list to real page or navigation routes.

**passive\_ttl** `string` (default: 30m)

How long the passive cookie lasts. After it expires the visitor's counter resets and they start fresh. Accepts Go duration strings such as `"15m"`, `"1h"`, or `"2h30m"`.

**max\_requests** `integer` (default: 50)

The number of passive-path requests a visitor can make before a CAPTCHA challenge is triggered. Once the count goes over this threshold within `request_window`, the next request becomes a challenge.

**request\_window** `string` (default: 10m)

The rolling window over which requests are counted. Requests older than this window do not count toward the budget. Accepts Go duration strings such as `"5m"`, `"10m"`, or `"1h"`.

> [!TIP]
>
> Keep `passive_paths` to a small list of real navigation routes. If you include paths that load many sub-resources (images, scripts, API calls), the budget fills up quickly and visitors may be challenged sooner than you intend.

> [!NOTE]
>
> Progressive mode and the verified cookie work together. Once a visitor has solved the CAPTCHA they receive a verified cookie, and progressive counting stops for them entirely until the verified cookie expires.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.