UrlMonitor Construct

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.

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

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

new UrlMonitor("advanced-url-monitor", {
  name: "Advanced URL Monitor",
  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

Property	Type	Required	Default	Description
`name`	`string`	✅	-	Friendly name for your monitor
`activated`	`boolean`	❌	`true`	Whether the monitor is enabled
`alertChannels`	`Array<AlertChannel \| AlertChannelRef>`	❌	`[]`	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

`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`

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

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

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

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Configuration

`UrlMonitor` Options

General Monitor Options

Examples

​Configuration

​UrlMonitor Options

​General Monitor Options

​Examples

Configuration

`UrlMonitor` Options

General Monitor Options

Examples