UrlMonitor Construct

Learn how to configure URL monitors with the Checkly CLI.

Learn more about URL Monitors in the URL monitor 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.

Basic Example

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

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

Configuration

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

URL 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

UrlMonitor Options

request · 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

Define assertions using the UrlAssertionBuilder to validate HTTP status codes:

UrlAssertionBuilder.statusCode().equals(200)
UrlAssertionBuilder.statusCode().notEquals(404)
UrlAssertionBuilder.statusCode().greaterThan(200)
UrlAssertionBuilder.statusCode().lessThan(300)

Examples:

Simple Website

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

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

degradedResponseTime · 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.

maxResponseTime · 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.

General Monitor Options

name · 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 · 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

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

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

locations · 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

// 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
})

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

activated · 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

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)],
  },
})

URL monitors only support status code assertions. For more complex assertions on response bodies, headers, or response time, use API checks 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.