---
title: "Dynamic Sampling · Unlighthouse"
canonical_url: "https://unlighthouse.dev/guide/guides/dynamic-sampling"
last_updated: "2026-01-25T03:25:52Z"
meta:
  description: "Automatically sample similar pages to reduce scan time for sites with many similar URLs like blogs or e-commerce."
  "og:description": "Automatically sample similar pages to reduce scan time for sites with many similar URLs like blogs or e-commerce."
  "og:title": "Dynamic Sampling · Unlighthouse"
---

Star Unlighthouse on GitHubUnlighthouse on GitHub

[**User Guide **](https://unlighthouse.dev/guide/getting-started/installation)

[**Integrations **](https://unlighthouse.dev/integrations/cli)

[**API **](https://unlighthouse.dev/api-doc/config)

**Guides**

# **Dynamic Sampling**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/dynamic-sampling.md)

Automatically group similar pages and scan only representative samples. This significantly reduces scan time for sites with many similar URLs like blogs, e-commerce product pages, or documentation sites.

## How it works

When dynamic sampling is enabled, it will group paths into chunks based on their path tree.

For example, let's imagine we have a blog on our site and there are hundreds of blog posts. Scanning every blog post will take a long time and may even break Unlighthouse.

The path structure is `**/blog/{post}**`.

Unlighthouse will turn this path structure into groups based on the `**/blog**` prefix. By default, it will sample 5 paths starting with this prefix.

A sample being a random selection of paths within this group.

For example if we have the posts:

- `**/blog/post-a**`
- `**/blog/post-b**`
- `**/blog/post-c**`
- `**/blog/post-d**`
- `**/blog/post-e**`
- `**/blog/post-f**`
- `**/blog/post-g**`
- `**/blog/post-h**`
- `**/blog/post-i**`

After sampling, we may end up with the random selection:

- `**/blog/post-c**`
- `**/blog/post-d**`
- `**/blog/post-e**`
- `**/blog/post-h**`
- `**/blog/post-i**`

## Usage

It is configured using the `**scanner.dynamicSampling**` option.

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  scanner: {
    dynamicSampling: 10, // Number of samples per group (default: 5)
  },
})
```

### Disable Dynamic Sampling

```ts
export default defineUnlighthouseConfig({
  scanner: {
    dynamicSampling: false,
  },
})
```

Alternatively, you can disable it using the CLI `**--disable-dynamic-sampling**`.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/dynamic-sampling.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/dynamic-sampling.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [~~edit this page ~~](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/dynamic-sampling.md) on GitHub or provide anonymous feedback below.

### **Related **

[**Route Definitions**](https://unlighthouse.dev/guide/guides/route-definitions) [**Large Sites**](https://unlighthouse.dev/guide/recipes/large-sites) [**URL Discovery**](https://unlighthouse.dev/guide/guides/url-discovery)

[**Docker** Run Unlighthouse site-wide Lighthouse scans in Docker containers. Dockerfile examples and CI/CD configuration.](https://unlighthouse.dev/guide/guides/docker) [**Static Reports** Generate static Lighthouse reports for your entire site. Export as HTML, CSV, or JSON. Deploy to Netlify, CloudFlare, or any static host.](https://unlighthouse.dev/guide/guides/generating-static-reports)

**On this page **

- [How it works](#how-it-works)
- [Usage](#usage)