> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UrlMonitor Construct

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

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

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

```ts Basic Example theme={null}
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)],
  },
})
```

```ts Advanced Example theme={null}
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**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `request` | `object` | ✅ | - | HTTP request configuration object |
| `intent` | `CheckIntent` | ❌ | - | Structured guidance for root cause analysis and check repair. See [General Monitor Options](#general-monitor-options). |
| `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. |

**General Monitor**

| 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<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` | ❌ | [`noRetries()`](https://www.checklyhq.com/docs/constructs/retry-strategy#default-retry-strategy) | 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

**request** `object` *required*

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

**Usage:**

```ts theme={null}
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**

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

**API Endpoint**

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

**Development Environment**

```ts theme={null}
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.

**degradedResponseTime** `number` (default: 3000)

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

**Usage:**

```ts highlight={4} theme={null}
// 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:**

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

**Examples:**

```ts theme={null}
// 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

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

```ts theme={null}
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.md).

### 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:**

```ts highlight={2} theme={null}
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:**

```ts highlight={2} theme={null}
new UrlMonitor("my-monitor", {
  frequency: Frequency.EVERY_1M,
  /* More options ... */
})
```

**Examples:**

**High Frequency**

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

**Standard Monitoring**

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

**Low Frequency**

```ts theme={null}
// 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`

**locations** `string[]` (default: \[])

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

**Usage:**

```ts highlight={2} theme={null}
new UrlMonitor("global-monitor", {
  locations: ["us-east-1", "eu-west-1", "ap-southeast-1"]
})
```

**Examples:**

**Global Coverage**

```ts theme={null}
// 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
})
```

**Regional Focus**

```ts theme={null}
// 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.

**activated** `boolean` (default: true)

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

**Usage:**

```ts highlight={2} theme={null}
new UrlMonitor("my-monitor", {
  activated: false // Disabled monitor
})
```

**Examples:**

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

**intent** `CheckIntent | null`

Describe what your check is intended to verify and the behavior that should be preserved. Checkly uses intent for root cause analysis across all check types. It is separate from `description` and does not replace executable assertions. Left unset, or set to `null`, the check has no intent.

> [!NOTE]
>
> Intent is used for [automatic repair](https://www.checklyhq.com/docs/resolve/automatic-check-repair.md) only for Browser and Multistep Checks.

The object accepts the following fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `goal` | `string` | Yes | The outcome your check should verify. Must contain 1–2,000 characters after trimming. |
| `constraints` | `CheckIntentConstraint[]` | No | Outcomes and guardrails that refine the goal. Omitted constraints become an empty array. |

Each constraint has a required `type` and `statement`:

* `REQUIRED_OUTCOME`: an outcome the check must verify.
* `MUST_PRESERVE`: behavior or an assertion that should be preserved when repairing the check.

Each `statement` must contain 1–1,000 characters after trimming. You can specify at most 20 constraints of each type. The CLI trims leading and trailing whitespace from the goal and statements and rejects unknown fields.

For example, configure intent on a Browser Check:

```ts theme={null}
import { BrowserCheck } from "checkly/constructs"

new BrowserCheck("dashboard-intent", {
  name: "Authenticated dashboard",
  code: {
    entrypoint: "./dashboard.spec.ts",
  },
  intent: {
    goal: "Verify that authenticated users can open the dashboard.",
    constraints: [
      {
        type: "REQUIRED_OUTCOME",
        statement: "Authentication succeeds for a valid user.",
      },
      {
        type: "MUST_PRESERVE",
        statement: "Do not remove or weaken the authentication assertion.",
      },
    ],
  },
})
```

## Examples

**Website Availability**

```ts theme={null}
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)],
  },
})
```

**API Health Check**

```ts theme={null}
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)
    ]
  }
})
```

**CDN Performance**

```ts theme={null}
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)],
  },
})
```

**Redirect Chain**

```ts theme={null}
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)
    ]
  }
})
```

**SSL Certificate Check**

```ts theme={null}
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)],
  },
})
```

**Multiple Status Codes**

```ts theme={null}
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)
    ]
  }
})
```

> [!NOTE]
>
> 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.md) instead.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.