Skip to main content
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.
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)],
  },
})

​
Configuration

The URL Monitoring configuration consists of specific URL monitoring options and inherited general monitoring options.
ParameterTypeRequiredDefaultDescription
requestobject✅-HTTP request configuration object
degradedResponseTimenumber❌3000Response time threshold in milliseconds for degraded status
maxResponseTimenumber❌5000Maximum response time in milliseconds before marking as failed
shouldFailboolean❌falseTreat HTTP error codes (4xx and 5xx) as passed. Please note that successful responses still pass. Only failed assertions will cause the check to fail.

​
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:
ParameterTypeRequiredDefaultDescription
urlstring✅-The HTTP(S) URL to monitor
followRedirectsboolean❌trueWhether to automatically follow 30x redirects
ipFamilyIPFamily❌IPv4IP family version to use for the connection
skipSSLboolean❌falseWhether to skip validation of SSL certificates
assertionsUrlAssertion[]❌[]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:
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:
// 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:
// 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

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.