---
title: Look up URL filter rules
description: "Look up URL filtering rule syntax, precedence, examples, validation, and limitations."
product: session-replay
lang: en
token_estimate: 2634
---
# Look up URL filter rules

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Use `ugcFilterRules` to replace sensitive URL content, such as user IDs or private query parameters, before the SDK records URLs in replays and heatmaps. This reference explains rule syntax, ordering, and validation. For installation and testing steps, [configure URL filtering](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules).

## What UGC Filter Rules do

UGC Filter Rules are configuration objects that define patterns to match URLs and specify replacement text. When the SDK captures URLs during session replay and heatmap recording, the SDK applies these rules to sanitize or anonymize sensitive information such as:

- User IDs
- Company names
- Sensitive query parameters
- Dynamic path segments containing private data

## Configure UGC Filter Rules

For SDK initialization and development checks, go to [Configure UGC Filter Rules](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules).

## Rule structure

Each UGC Filter Rule is an object with two required properties:

```typescript
type UGCFilterRule = {
  selector: string; // Glob pattern to match URLs
  replacement: string; // Text to replace the matched URL
};
```

### Properties

| Property | Description |
| --- | --- |
| `selector` | A glob pattern string that matches URLs. Supports `*` (any characters). Supports multiple wildcards in domains and paths. |
| `replacement` | The replacement text that the SDK uses when the selector pattern matches a URL. |

### Selector pattern examples

- `https://*.domain.com/*` matches any subdomain and any path.
- `https://site.com/*/*` matches two path segments.
- `https://api.com/*/data/*` matches specific patterns with wildcards.

## Glob pattern syntax

The `selector` field uses basic glob patterns for URL matching. The current implementation supports:

| Pattern | Description | Example |
| --- | --- | --- |
| `*` | Matches any sequence of characters | `https://example.com/*` matches `https://example.com/anything` |

Supported wildcard locations:

| Location | Description | Example |
| --- | --- | --- |
| Multiple wildcards | Use multiple `*` in a single pattern | `https://*.domain.com/*/*` |
| Domain wildcards | `*` works in domain names | `*.projecttool.com` |
| Path wildcards | Multiple `*` in URL paths | `/projects/*/boards/*` |

The SDK doesn't support advanced glob features such as `**`, `[abc]`, `{option1,option2}`, and others.

## Examples

### Filter project management tool URLs

Remove organization names and sensitive identifiers from project management URLs:

```javascript
// Filter ticket URLs
{
  selector: "https://*.projecttool.com/browse/*",
  replacement: "https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER"
}

// Filter project list URLs
{
  selector: "https://*.projecttool.com/software/projects/*/list*",
  replacement: "https://ORG_NAME.projecttool.com/software/projects/PROJECT_NAME/list"
}

// Filter board URLs
{
  selector: "https://*.projecttool.com/software/projects/*/boards/*",
  replacement: "https://ORG_NAME.projecttool.com/software/projects/boards/BOARD_ID"
}

// Filter wiki pages
{
  selector: "https://*.projecttool.com/wiki/spaces/*/pages/*",
  replacement: "https://ORG_NAME.projecttool.com/wiki/spaces/SPACE_NAME/pages/PAGE_NAME"
}
```

### Filter code repository URLs

Remove repository details and sensitive paths:

```javascript
// Filter repository file browser with branch and file paths
{
  selector: "https://codehost.com/*/*/tree/*/*",
  replacement: "https://codehost.com/USER/REPO/tree/BRANCH/FILES"
}

// Filter repository branch view
{
  selector: "https://codehost.com/*/*/tree/*",
  replacement: "https://codehost.com/USER/REPO/tree/BRANCH"
}
```

### Filter user IDs from profile URLs

Remove user IDs from profile URLs:

```javascript
{
  selector: 'https://myapp.com/user/*/profile',
  replacement: 'https://myapp.com/user/USER_ID/profile'
}
```

Before: `https://myapp.com/user/12345/profile`  
After: `https://myapp.com/user/USER_ID/profile`

### Sanitize query parameters

Remove sensitive query parameters:

```javascript
{
  selector: 'https://myapp.com/dashboard?token=*',
  replacement: 'https://myapp.com/dashboard?token=REDACTED'
}
```

Before: `https://myapp.com/dashboard?token=abc123xyz`  
After: `https://myapp.com/dashboard?token=REDACTED`

### Filter URLs with multiple path segments

Filter URLs with multiple dynamic segments:

```javascript
{
  selector: 'https://api.example.com/users/*/documents/*/*',
  replacement: 'https://api.example.com/users/USER_ID/documents/CATEGORY/DOCUMENT_ID'
}
```

Before: `https://api.example.com/users/john123/documents/private/contract-2023.pdf`  
After: `https://api.example.com/users/USER_ID/documents/CATEGORY/DOCUMENT_ID`

### Filter email addresses in URLs

Remove email addresses from URL paths:

```javascript
{
  selector: 'https://myapp.com/user/*/settings',
  replacement: 'https://myapp.com/user/EMAIL_ADDRESS/settings'
}
```

Before: `https://myapp.com/user/john.doe@company.com/settings`  
After: `https://myapp.com/user/EMAIL_ADDRESS/settings`

## Advanced usage

### Rule precedence with multiple rules

The SDK applies rules in order, and the first matching rule wins:

```javascript
ugcFilterRules: [
  // More specific rule - will match first
  {
    selector: "https://example.com/user/*/profile/settings",
    replacement: "https://example.com/user/USER_ID/profile/settings",
  },
  // Less specific rule - will only match if first rule doesn't
  {
    selector: "https://example.com/user/*/*",
    replacement: "https://example.com/user/USER_ID/ACTION",
  },
];
```

### Complete configuration example

```javascript
import { sessionReplay } from "@amplitude/session-replay-browser";

sessionReplay.init("YOUR_API_KEY", {
  interactionConfig: {
    enabled: true,
    ugcFilterRules: [
      // Filter project management tool URLs
      {
        selector: "https://*.projecttool.com/browse/*",
        replacement: "https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER",
      },
      {
        selector: "https://*.projecttool.com/software/projects/*/boards/*",
        replacement:
          "https://ORG_NAME.projecttool.com/software/projects/PROJECT_NAME/boards/BOARD_ID",
      },

      // Filter code repository URLs
      {
        selector: "https://codehost.com/*/*/tree/*/*",
        replacement: "https://codehost.com/USER/REPO/tree/BRANCH/FILES",
      },
      {
        selector: "https://codehost.com/*/*/tree/*",
        replacement: "https://codehost.com/USER/REPO/tree/BRANCH",
      },

      // Filter internal application URLs
      {
        selector: "https://myapp.com/user/*/profile",
        replacement: "https://myapp.com/user/USER_ID/profile",
      },
      {
        selector: "https://api.myapp.com/*?token=*",
        replacement: "https://api.myapp.com/ENDPOINT?token=REDACTED",
      },

      // Filter admin URLs completely
      {
        selector: "https://myapp.com/admin/*",
        replacement: "https://myapp.com/admin/ADMIN_SECTION",
      },
    ],
  },
});
```

## Error handling and validation

The SDK validates UGC Filter Rules during initialization.

### Validation rules

| Rule | Requirement |
| --- | --- |
| Type validation | Both `selector` and `replacement` must be strings. |
| URL format validation | The `selector` must be a valid URL pattern that starts with `/`, `http://`, or `https://`. |
| Non-empty | Selectors can't be empty or whitespace-only. |

### Error examples

```javascript
// ❌ Invalid - non-string selector
{
  selector: 123,
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with selector and replacement properties

// ❌ Invalid - non-string replacement
{
  selector: 'https://example.com/*',
  replacement: 456
}
// Error: ugcFilterRules must be an array of objects with selector and replacement properties

// ❌ Invalid - selector doesn't start with / or http(s)://
{
  selector: 'example.com/path',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs

// ❌ Invalid - empty selector
{
  selector: '',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs

// ❌ Invalid - whitespace-only selector
{
  selector: '   ',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs
```

## Best practices

### Order rules by specificity

Place more specific patterns before general ones:

```javascript
ugcFilterRules: [
  // More specific patterns first
  {
    selector: "https://codehost.com/*/*/tree/*/*",
    replacement: "https://codehost.com/USER/REPO/tree/BRANCH/FILES",
  },
  // Less specific patterns later
  {
    selector: "https://codehost.com/*/*/tree/*",
    replacement: "https://codehost.com/USER/REPO/tree/BRANCH",
  },
  // Most general patterns last
  {
    selector: "https://codehost.com/*/*",
    replacement: "https://codehost.com/USER/REPO",
  },
];
```

### Use descriptive replacements

Make replacements clear and meaningful:

```javascript
// ✅ Good - descriptive
{
  selector: 'https://*.projecttool.com/browse/*',
  replacement: 'https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER'
}

// ❌ Avoid - unclear
{
  selector: 'https://*.projecttool.com/browse/*',
  replacement: 'https://XXX.projecttool.com/browse/XXX'
}
```

### Test patterns in a development environment first

Go to [Test patterns in a development environment first](https://amplitude.com/docs/session-replay/configure-ugc-filter-rules#test-patterns-in-a-development-environment-first) for example URLs to check.

## Common issues

| Issue | Resolution |
| --- | --- |
| Rules not applied | Ensure `interactionConfig.enabled` is `true`. |
| Pattern not matching | Use only `*` patterns. |
| Wrong order | Check that specific rules come before general ones. |
| Invalid patterns | Verify that selectors only use supported glob syntax (`*`). |

## Limitations

- The SDK applies rules to full URLs, not individual URL components.
- The SDK supports only `*` (any characters) for glob patterns.
- The SDK doesn't support advanced glob features such as `**`, `[abc]`, `{option1,option2}`, ranges, and negation.
- Rules can't modify URL structure. Rules can only replace entire URLs.

The SDK uses a simple glob-to-regex conversion that supports multiple wildcards and domain patterns.