> Meticulous records real user sessions from a web app and replays them against each commit to catch visual regressions.
>
> Full AI-readable docs index (complete project setup journey + every page as markdown): https://app.meticulous.ai/llms.txt

# Filter Sessions by Start URL

Meticulous automatically replays the set of sessions that will exhaustively test your change. However, when triggering a
run with [`ci run-with-uploaded-asset-chunks`](/docs/how-to/incremental-asset-upload), you can pass a session filter
to restrict the set of sessions executed beyond that, by filtering to only sessions that start on specific routes — for
example to only test the part of your app affected by a change. This can be useful in extremely large applications,
where your build system may be able to more tightly isolate the blast radius of a change than Meticulous can via static
analysis.

## Usage

Write a JSON file with a `session-start-url-matches-any-regex` key listing one or more regexes:

```bash
cat > session-filter.json <<'EOF'
{
  "session-start-url-matches-any-regex": [
    "/checkout/",
    "^https://app\\.example\\.com/settings"
  ]
}
EOF

npx @alwaysmeticulous/cli ci run-with-uploaded-asset-chunks \
  --apiToken="$METICULOUS_API_TOKEN" \
  --commitSha="$CI_COMMIT_SHA" \
  --assetReferencesManifest="./assets-manifest.json" \
  --sessionFilter="./session-filter.json"
```

A session is replayed if its **start URL** — the URL the session started recording on — matches **at least one** of the
regexes. The same filtered set of sessions is used for both the head run and any base run created to compare against, so
comparisons stay consistent. If the filter matches no sessions, the command fails with an error rather than triggering an
empty run.

## Regex syntax

Regexes use [Google's RE2 syntax](https://github.com/google/re2/wiki/Syntax). They are validated before the run is
triggered, so a regex that doesn't compile fails fast in the CLI with a clear error.

> **info: Filtering only affects which sessions run**
> The session filter narrows a single test run down from the project's selected sessions; it doesn't change which sessions
> Meticulous records or selects. Runs triggered without `--sessionFilter` still replay the full selected set.