# UrlMonitor Construct - Checkly Docs

> Learn how to configure URL monitors with the Checkly CLI.

Source: https://www.checklyhq.com/docs/constructs/url-monitor/

---

- Configuration UrlMonitor Options
- UrlMonitor Assertions
- General Monitor Options

- Examples

DETECT

# UrlMonitor Construct

Learn how to configure URL monitors with the Checkly CLI.

Learn more about URL Monitors in [the URL monitor overview](https://www.checklyhq.com/docs/detect/uptime-monitoring/url-monitors/overview).

Use URL Monitors to track basic availability and HTTP status codes of your services and websites. The examples below show how to configure monitoring for different types of HTTP endpoints.

Prerequisites

Before creating URL Monitors, ensure you have:

- An initialized Checkly CLI project

- URLs or HTTP endpoints you want to monitor

- Understanding of HTTP status codes and response behavior

- Network access to the URLs you want to monitor

For additional setup information, see [CLI overview](https://www.checklyhq.com/docs/cli/overview).

```
import { Frequency, UrlAssertionBuilder, UrlMonitor } from "checkly/constructs"

new UrlMonitor("url-monitor", {
name: "Url Monitor",
description: "[httpbin.org/get](https://httpbin.org/get) should return **200** status code.",
activated: true,
maxResponseTime: 10000,
degradedResponseTime: 5000,
frequency: Frequency.EVERY_5M,
request: {
url: "https://httpbin.org/get",
assertions: [UrlAssertionBuilder.statusCode().equals(200)],
},
})
```

```
import { Frequency, UrlAssertionBuilder, UrlMonitor } from "checkly/constructs"

new UrlMonitor("advanced-url-monitor", {
name: "Advanced URL Monitor",
description: "**API health check** returns 200.",
activated: true,
frequency: Frequency.EVERY_5M,
locations: ["us-east-1", "eu-west-1"],
maxResponseTime: 5000,
degradedResponseTime: 2000,
tags: ["api", "production", "critical"],
request: {
url: "https://api.example.com/health",
skipSSL: false,
followRedirects: true,
assertions: [UrlAssertionBuilder.statusCode().equals(200)],
},
})
```

## ​ Configuration

The URL Monitoring configuration consists of specific URL monitoring options and inherited general monitoring options.

- URL Monitor
- General Monitor

Parameter Type Required Default Description

`request` `object` ✅ - HTTP request configuration object

`degradedResponseTime` `number` ❌ `3000` Response time threshold in milliseconds for degraded status

`maxResponseTime` `number` ❌ `5000` Maximum response time in milliseconds before marking as failed

`shouldFail` `boolean` ❌ false Treat HTTP error codes (4xx and 5xx) as passed. Please note that successful responses still pass. Only failed assertions will cause the check to fail.

Property Type Required Default Description

`name` `string` ✅ - Friendly name for your monitor

`description` `string` ❌ `null` A description of the monitor. Supports markdown. Max 500 characters

`activated` `boolean` ❌ `true` Whether the monitor is enabled

`alertChannels` `Array ` ❌ `[]` Array of AlertChannel objects for notifications

`alertEscalationPolicy` `AlertEscalationPolicy` ❌ - Advanced alert escalation settings

`frequency` `Frequency` ❌ `EVERY_10M` How often to run your monitor

`group` `CheckGroupV1` `CheckGroupV2` ❌ - The CheckGroup this monitor belongs to

`locations` `string[]` ❌ `[]` Array of public location codes

`privateLocations` `string[]` ❌ `[]` Array of Private Location slugs

`muted` `boolean` ❌ `false` Whether alert notifications are muted

`tags` `string[]` ❌ `[]` Array of tags to organize monitors

`testOnly` `boolean` ❌ `false` Only run with test, not during deploy

`retryStrategy` `RetryStrategy` ❌ - Strategy for configuring retries

`runParallel` `boolean` ❌ `false` Run monitors in parallel or round-robin

`triggerIncident` `IncidentTrigger` ❌ - Create and resolve an incident based on the check’s alert configuration

### ​ `UrlMonitor` Options

​

object

required

HTTP request configuration that defines the URL to monitor and how to handle the request. **Usage:**

```
new UrlMonitor("url-monitor", {
request: {
url: "https://example.com",
followRedirects: true,
assertions: [
UrlAssertionBuilder.statusCode().equals(200)
]
}
})
```

**Parameters:** Parameter Type Required Default Description

`url` `string` ✅ - The HTTP(S) URL to monitor

`followRedirects` `boolean` ❌ `true` Whether to automatically follow 30x redirects

`ipFamily` `IPFamily` ❌ `IPv4` IP family version to use for the connection

`skipSSL` `boolean` ❌ `false` Whether to skip validation of SSL certificates

`assertions` `UrlAssertion[]` ❌ `[]` Response assertions using `UrlAssertionBuilder`

**Examples:**
- Simple Website
- API Endpoint
- Development Environment

```
new UrlMonitor('website-check', {
name: 'Website Availability',
request: {
url: 'https://example.com',
followRedirects: true,
assertions: [
UrlAssertionBuilder.statusCode().equals(200)
]
}
})
```

```
new UrlMonitor("api-health", {
name: "API Health Check",
request: {
url: "https://api.example.com/health",
followRedirects: false,
skipSSL: false,
assertions: [UrlAssertionBuilder.statusCode().equals(200)],
},
})
```

```
new UrlMonitor("dev-endpoint", {
name: "Development Environment",
request: {
url: "https://dev.example.com",
followRedirects: true,
skipSSL: true, // Skip SSL for dev environment
assertions: [UrlAssertionBuilder.statusCode().equals(200)],
},
})
```

**Use cases**: Website availability, API health checks, service uptime monitoring.

​

number

default: "3000"

Response time threshold in milliseconds for marking the monitor as degraded (warning state). **Usage:**

```
// Progressive performance monitoring
new UrlMonitor("performance-tiers", {
name: "Website Performance Tiers",
degradedResponseTime: 1500, // Warn at 1.5s
maxResponseTime: 3000, // Fail at 3s
request: {
url: "https://example.com",
assertions: [UrlAssertionBuilder.statusCode().equals(200)],
},
})
```

**Use cases**: Early performance warnings, gradual degradation detection.

​

number

default: "5000"

Maximum response time in milliseconds before the monitor is marked as failed. **Usage:**

```
new UrlMonitor("fast-site", {
name: "Fast site",
maxResponseTime: 3000, // 3 seconds max
request: {
url: "https://fast.example.com",
},
})
```

**Examples:**

```
// Fast website requirement
new UrlMonitor("performance-critical", {
name: "Performance Critical Site",
maxResponseTime: 1000, // Fail at 1 second
degradedResponseTime: 500, // Warning at 500ms
request: {
url: "https://critical.example.com",
},
})

// API with reasonable timeout
new UrlMonitor("api-timeout", {
name: "API with Timeout",
maxResponseTime: 10000, // 10 seconds
request: {
url: "https://api.example.com/slow-operation",
},
})
```

**Use cases**: Performance monitoring, SLA compliance, user experience optimization.

### ​ `UrlMonitor` Assertions

To define `assertions` for the `request` of an `UrlMonitor` you should use the `UrlAssertionBuilder`. The following source is available for URL monitor assertions:

- `statusCode()`: Assert the HTTP status code for the HTTP response, e.g. 200 or 201

Here is an example:

- Assert the status code of a HTTP request

```
UrlAssertionBuilder.statusCode().equals(200)
// Equivalent to:
{ source: 'STATUS_CODE', comparison: 'EQUALS', target: '200' }
```

```
UrlAssertionBuilder.statusCode().lessThan(300)
// Equivalent to:
{ source: 'STATUS_CODE', comparison: 'LESS_THAN', target: '300' }
```

Learn more in our docs on [Assertions](https://www.checklyhq.com/docs/detect/assertions).

### ​ General Monitor Options

​

string

required

Friendly name for your URL monitor that will be displayed in the Checkly dashboard and used in notifications. **Usage:**

```
new UrlMonitor("my-monitor", {
name: "Website Uptime Monitor",
/* More options ... */
})
```

​

Frequency

How often the URL monitor should run. Use the `Frequency` enum to set the check interval. **Usage:**

```
new UrlMonitor("my-monitor", {
frequency: Frequency.EVERY_1M,
/* More options ... */
})
```

**Examples:**
- High Frequency
- Standard Monitoring
- Low Frequency

```
// Critical service monitoring
new UrlMonitor("critical-service", {
name: "Critical Service Uptime",
frequency: Frequency.EVERY_30S, // Every 30 seconds
maxResponseTime: 2000
})
```

```
// Regular website monitoring
new UrlMonitor("website-monitor", {
name: "Website Availability",
frequency: Frequency.EVERY_5M, // Every 5 minutes
maxResponseTime: 5000
})
```

```
// Background service monitoring
new UrlMonitor("background-service", {
name: "Background Service Health",
frequency: Frequency.EVERY_30M, // Every 30 minutes
maxResponseTime: 10000
})
```

**Available frequencies**: `EVERY_10S`, `EVERY_20S`, `EVERY_30S`, `EVERY_1M`, `EVERY_2M`, `EVERY_5M`, `EVERY_10M`, `EVERY_15M`, `EVERY_30M`, `EVERY_1H`, `EVERY_2H`, `EVERY_3H`, `EVERY_6H`, `EVERY_12H`, `EVERY_24H`

​

string[]

default: "[]"

Array of public location codes where the URL monitor should run from. Multiple locations provide geographic coverage. **Usage:**

```
new UrlMonitor("global-monitor", {
locations: ["us-east-1", "eu-west-1", "ap-southeast-1"]
})
```

**Examples:**
- Global Coverage
- Regional Focus

```
// Worldwide monitoring
new UrlMonitor("global-website", {
name: "Global Website Monitoring",
frequency: Frequency.EVERY_2M,
locations: [
"us-east-1", // N. Virginia
"us-west-1", // N. California
"eu-west-1", // Ireland
"ap-southeast-1", // Singapore
"ap-northeast-1" // Tokyo
],
maxResponseTime: 5000
})
```

```
// European users focus
new UrlMonitor("eu-service", {
name: "European Service Monitor",
frequency: Frequency.EVERY_1M,
locations: ["eu-west-1", "eu-central-1"]
})
```

**Use cases**: Global performance monitoring, regional compliance, CDN performance validation.

​

boolean

default: "true"

Whether the URL monitor is enabled and will run according to its schedule. **Usage:**

```
new UrlMonitor("my-monitor", {
activated: false // Disabled monitor
})
```

**Examples:**

```
// Temporarily disable a monitor
new UrlMonitor("maintenance-site", {
name: "Site Under Maintenance",
activated: false,
request: {
url: "https://maintenance.example.com"
}
})
```

## ​ Examples

- Website Availability
- API Health Check
- CDN Performance
- Redirect Chain
- SSL Certificate Check
- Multiple Status Codes

```
new UrlMonitor("website-availability", {
name: "Main Website Availability",
frequency: Frequency.EVERY_1M,
locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
maxResponseTime: 3000,
degradedResponseTime: 1500,
tags: ["website", "critical"],
request: {
url: "https://example.com",
followRedirects: true,
skipSSL: false,
assertions: [UrlAssertionBuilder.statusCode().equals(200)],
},
})
```

```
new UrlMonitor("api-health-check", {
name: "API Health Endpoint",
frequency: Frequency.EVERY_30S,
locations: ["us-east-1", "eu-west-1"],
maxResponseTime: 2000,
degradedResponseTime: 1000,
tags: ["api", "health", "critical"],
request: {
url: "https://api.example.com/health",
followRedirects: false,
assertions: [
UrlAssertionBuilder.statusCode().equals(200)
]
}
})
```

```
new UrlMonitor("cdn-performance", {
name: "CDN Asset Performance",
frequency: Frequency.EVERY_5M,
locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
maxResponseTime: 5000,
degradedResponseTime: 2000,
tags: ["cdn", "assets", "performance"],
request: {
url: "https://cdn.example.com/assets/main.css",
followRedirects: true,
assertions: [UrlAssertionBuilder.statusCode().equals(200)],
},
})
```

```
new UrlMonitor("redirect-chain", {
name: "Redirect Chain Monitor",
frequency: Frequency.EVERY_10M,
maxResponseTime: 4000,
degradedResponseTime: 2000,
tags: ["redirects", "seo"],
request: {
url: "https://old.example.com/page",
followRedirects: true,
assertions: [
UrlAssertionBuilder.statusCode().equals(200)
]
}
})
```

```
new UrlMonitor("ssl-certificate-check", {
name: "SSL Certificate Validity",
frequency: Frequency.EVERY_1H,
locations: ["us-east-1"],
maxResponseTime: 10000,
degradedResponseTime: 5000,
tags: ["ssl", "security"],
request: {
url: "https://secure.example.com",
followRedirects: false,
skipSSL: false, // Ensure SSL validation
assertions: [UrlAssertionBuilder.statusCode().equals(200)],
},
})
```

```
new UrlMonitor("maintenance-page", {
name: "Maintenance Page Check",
frequency: Frequency.EVERY_5M,
maxResponseTime: 3000,
degradedResponseTime: 1500,
tags: ["maintenance", "status"],
request: {
url: "https://status.example.com",
followRedirects: true,
assertions: [
// Accept both 200 (normal) and 503 (maintenance)
UrlAssertionBuilder.statusCode().between(200, 200),
UrlAssertionBuilder.statusCode().between(503, 503)
]
}
})
```

URL monitors only support status code assertions. For more complex assertions on response bodies, headers, or response time, use [API checks](https://www.checklyhq.com/docs/constructs/api-check) instead.

When `skipSSL` is set to `true`, SSL certificate validation is bypassed. Use this only for testing environments or when monitoring services with self-signed certificates.

Was this page helpful?

[Suggest edits](https://github.com/checkly/docs/edit/main/constructs/url-monitor.mdx)[Raise issue](https://github.com/checkly/docs/issues/new?title=Issue%20on%20docs&body=Path:%20/constructs/url-monitor)

[Dynamic monitor creation Previous](https://www.checklyhq.com/docs/constructs/dynamic-monitor-creation)[DnsMonitor Construct Next](https://www.checklyhq.com/docs/constructs/dns-monitor)

[x](https://x.com/checklyhq)[github](https://github.com/checkly)[linkedin](https://linkedin.com/company/checkly)

[Powered by This documentation is built and hosted on Mintlify, a developer documentation platform](https://www.mintlify.com/?utm_campaign=poweredBy&utm_medium=referral&utm_source=checkly-422f444a)