---
title: "Conditions - Serpwise Documentation"
description: "Conditions define when a rule fires. Combine URL, request, and response conditions with AND/OR logic."
url: "https://serpwise.ai/docs/conditions/"
source: "https://serpwise.ai/docs/conditions/"
---
[Back to Serpwise](/)

Serpwise Documentation

Connect · Configure · Execute

Search documentation

`/`

No documentation found.

↑↓ Navigate Enter to open

Browse documentation

Conditions are the “when” part of a rule. The gateway evaluates a rule’s conditions against every incoming request and its corresponding origin response. When the conditions evaluate to `true`, the rule’s actions are applied.

## Condition Groups and Logic

Conditions are organized into **groups** with AND or OR logic:

- **AND** - all conditions in the group must be true
- **OR** - at least one condition in the group must be true

Groups can be nested for complex logic. For example:

```
(url.path starts_with /blog/) AND (request.is_bot equals true)
```

Or more complex:

```
(url.path starts_with /products/) AND (
  (response.status_code equals 200) OR (response.status_code equals 301)
)
```

* * *

## URL Conditions

URL conditions match against parts of the request URL.

### `url.path`

The URL path, not including query string or fragment.

```
/blog/my-first-post
/products/blue-widget
/
```

### `url.full`

The complete URL including scheme, host, path, and query string.

```
https://www.example.com/search?q=shoes&color=blue
```

### `url.query_param`

A specific query parameter value. Requires specifying the parameter name.

```
Field:  url.query_param
Name:   color
Value:  blue
```

Matches: `/search?q=shoes&color=blue`

* * *

## Request Conditions

Request conditions match against properties of the incoming HTTP request.

### `request.method`

The HTTP method of the request.

Common values: `GET`, `POST`, `HEAD`, `PUT`, `DELETE`

### `request.header`

A specific HTTP request header value. Requires specifying the header name.

```
Field:  request.header
Name:   Accept-Language
Value:  en-US
```

### `request.user_agent`

The full `User-Agent` string sent by the client.

Useful for targeting specific browsers, crawlers, or custom clients.

### `request.is_bot`

Whether the request was identified as a known bot. Values: `true` or `false`.

Serpwise identifies bots by matching the `User-Agent` against a registry of 50+ known crawlers.

### `request.bot_name`

The name of the identified bot (only meaningful when `request.is_bot` is `true`).

Common values include: `Googlebot`, `Bingbot`, `GPTBot`, `ClaudeBot`, `PerplexityBot`, `AhrefsBot`, `SemrushBot`

* * *

## Response Conditions

Response conditions match against properties of the response returned by your origin server. The gateway evaluates these after fetching from origin.

### `response.status_code`

The HTTP status code returned by origin.

```
200, 301, 302, 404, 500
```

### `response.content_type`

The `Content-Type` header value of the origin response.

```
text/html; charset=utf-8
application/json
```

### `response.header`

A specific HTTP response header value. Requires specifying the header name.

```
Field:  response.header
Name:   X-Custom-Header
Value:  production
```

### `response.body_contains`

Whether the origin response HTML body contains a specific substring. Useful for targeting pages with specific content characteristics.

* * *

## Operators

All conditions use an operator to define how the field value is compared to the target value.

| Operator        | Description                                 | Example                                     |
|-----------------|---------------------------------------------|---------------------------------------------|
| `equals`        | Exact match (case-sensitive)                | `url.path equals /about`                    |
| `not_equals`    | Does not exactly match                      | `response.status_code not_equals 200`       |
| `contains`      | Field contains the value as a substring     | `url.path contains /blog/`                  |
| `not_contains`  | Field does not contain the value            | `request.user_agent not_contains bot`       |
| `starts_with`   | Field begins with the value                 | `url.path starts_with /products/`           |
| `ends_with`     | Field ends with the value                   | `url.path ends_with .html`                  |
| `matches_regex` | Field matches a regular expression          | `url.path matches_regex ^/category/[a-z]+$` |
| `exists`        | Field is present (non-empty)                | `url.query_param[utm_source] exists`        |
| `not_exists`    | Field is absent or empty                    | `request.header[Authorization] not_exists`  |
| `greater_than`  | Field value is greater (numeric comparison) | `response.status_code greater_than 399`     |
| `less_than`     | Field value is less (numeric comparison)    | `response.status_code less_than 300`        |

### Regex Operator

The `matches_regex` operator supports standard regular expression syntax. Capture groups are supported and can be referenced in some actions.

```
^/blog/[0-9]{4}/[0-9]{2}/.+$   ← matches dated blog posts: /blog/2024/03/my-post
^/(en|de|fr)/.*$                ← matches language-prefixed paths
```

* * *

## Condition Examples

### Target all blog pages

```
url.path starts_with /blog/
```

### Target Googlebot only

```
request.bot_name equals Googlebot
```

### Target AI crawlers

```
request.bot_name equals GPTBot
OR
request.bot_name equals ClaudeBot
OR
request.bot_name equals PerplexityBot
```

### Target paginated pages

```
url.query_param[page] exists
```

### Target error pages from origin

```
response.status_code greater_than 399
```

### Target pages with UTM parameters

```
url.query_param[utm_source] exists
```

### Target non-HTML responses (to skip modification)

```
response.content_type not_contains text/html
```