HTTP Monitors
HTTP Monitors
HTTP monitors let you track the uptime and performance of any URL. WatchCron checks your endpoints at the interval you define and alerts you when something goes wrong — a non-200 status code, a missing keyword, slow response time, or an expiring SSL certificate. The API gives you full control over creating, updating, pausing, and deleting monitors programmatically.
List HTTP monitors
/api/v1/http-monitors
Returns a paginated list of all HTTP monitors in the project associated with your API key.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | — | Filter by status: up, down, paused, or new |
per_page | integer | 25 | Results per page |
page | integer | 1 | Page number |
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/http-monitors?status=down&per_page=10"
$response = Http::withToken('YOUR_API_KEY') ->get('https://watchcron.com/api/v1/http-monitors', [ 'status' => 'down', 'per_page' => 10, ]); $monitors = $response->json('data');
import requests response = requests.get( "https://watchcron.com/api/v1/http-monitors", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"status": "down", "per_page": 10}, ) monitors = response.json()["data"]
const response = await fetch( "https://watchcron.com/api/v1/http-monitors?status=down&per_page=10", { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: monitors } = await response.json();
req, _ := http.NewRequest("GET", "https://watchcron.com/api/v1/http-monitors?status=down&per_page=10", nil) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Response 200 OK
{
"data": [
{
"uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Production Website",
"url": "https://example.com",
"method": "GET",
"status": "up",
"interval_seconds": 300,
"timeout_seconds": 10,
"expected_status_code": 200,
"keyword": "Welcome",
"keyword_absent": false,
"grace_period_seconds": 60,
"response_time_threshold_ms": 2000,
"ssl_check": true,
"ssl_expiry_days_warn": 14,
"ssl_expiry_at": "2027-03-15T00:00:00Z",
"ssl_issuer": "Let's Encrypt",
"is_active": true,
"last_checked_at": "2026-10-26T12:05:00Z",
"last_response_time_ms": 187,
"last_status_code": 200,
"last_error": null,
"last_up_at": "2026-10-26T12:05:00Z",
"last_down_at": null,
"maintenance_windows": [],
"created_at": "2026-06-10T08:30:00Z",
"updated_at": "2026-10-26T12:05:00Z"
}
],
"meta": {
"pagination": {
"total": 18,
"per_page": 10,
"current_page": 1,
"last_page": 2
}
}
}
HTTP monitor object
Every HTTP monitor response includes these fields:
| Field | Type | Description |
|---|---|---|
uuid | string | Unique identifier (UUID v4). Used in all API URLs. |
name | string | Display name of the monitor |
url | string | The URL being monitored |
method | string | HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS |
status | string | Current status: new, up, down, or paused |
interval_seconds | integer | Check interval in seconds (minimum 30) |
timeout_seconds | integer | Request timeout in seconds (1–60) |
expected_status_code | integer|null | Expected HTTP status code (100–599). If null, any 2xx is considered successful. |
keyword | string|null | Keyword to search for in the response body |
keyword_absent | boolean | If true, the check fails when the keyword IS found (absence check) |
grace_period_seconds | integer|null | Seconds to wait before triggering an alert after a failure |
response_time_threshold_ms | integer|null | Alert if response time exceeds this value (in milliseconds) |
ssl_check | boolean | Whether SSL certificate monitoring is enabled |
ssl_expiry_days_warn | integer|null | Days before SSL expiry to send a warning |
ssl_expiry_at | string|null | ISO 8601 timestamp of SSL certificate expiry (read-only) |
ssl_issuer | string|null | SSL certificate issuer name (read-only) |
is_active | boolean | Whether the monitor is active (not paused) |
last_checked_at | string|null | ISO 8601 timestamp of most recent check |
last_response_time_ms | integer|null | Response time of the most recent check in milliseconds |
last_status_code | integer|null | HTTP status code from the most recent check |
last_error | string|null | Error message from the most recent check (null if successful) |
last_up_at | string|null | ISO 8601 timestamp of when the monitor was last up |
last_down_at | string|null | ISO 8601 timestamp of when the monitor last went down |
maintenance_windows | array | List of maintenance window objects (checks are skipped during these periods) |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Status values
| Status | Meaning |
|---|---|
new | Monitor created, waiting for the first check |
up | The URL is reachable and all conditions are met |
down | The URL is unreachable, returned an unexpected status, or failed a keyword/response-time check |
paused | Monitoring is paused — no checks or alerts will fire |
Create an HTTP monitor
/api/v1/http-monitors
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Monitor name (max 255 characters) |
url | string | Yes | URL to monitor (max 2048 characters) |
method | string | No | HTTP method (defaults to GET). One of: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
interval_seconds | integer | No | Check interval in seconds (min 30, defaults to 300) |
timeout_seconds | integer | No | Request timeout in seconds (1–60, defaults to 10) |
expected_status_code | integer | No | Expected HTTP status code (100–599). Omit to accept any 2xx. |
keyword | string | No | Keyword to search for in the response body (max 255 characters) |
keyword_absent | boolean | No | Set to true to alert when the keyword IS found |
grace_period_seconds | integer | No | Seconds to wait before alerting (min 0) |
response_time_threshold_ms | integer | No | Alert when response time exceeds this value in ms (min 0) |
ssl_check | boolean | No | Enable SSL certificate monitoring |
ssl_expiry_days_warn | integer | No | Days before SSL expiry to warn (min 1) |
headers | array | No | Custom request headers as key-value pairs |
http_auth_user | string | No | HTTP Basic Auth username (max 255 characters) |
http_auth_pass | string | No | HTTP Basic Auth password (max 255 characters) |
maintenance_windows | array | No | Maintenance window definitions |
keyword_absent to true to invert this — the check passes only when the keyword is NOT found. This is useful for detecting error messages like “Service Unavailable” appearing on a page.Example: create a monitor with keyword and SSL check
curl -X POST https://watchcron.com/api/v1/http-monitors \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production Website", "url": "https://example.com", "method": "GET", "interval_seconds": 300, "timeout_seconds": 10, "expected_status_code": 200, "keyword": "Welcome", "ssl_check": true, "ssl_expiry_days_warn": 14, "grace_period_seconds": 60, "response_time_threshold_ms": 2000 }'
$response = Http::withToken('YOUR_API_KEY') ->post('https://watchcron.com/api/v1/http-monitors', [ 'name' => 'Production Website', 'url' => 'https://example.com', 'method' => 'GET', 'interval_seconds' => 300, 'timeout_seconds' => 10, 'expected_status_code' => 200, 'keyword' => 'Welcome', 'ssl_check' => true, 'ssl_expiry_days_warn' => 14, 'grace_period_seconds' => 60, 'response_time_threshold_ms' => 2000, ]); $monitor = $response->json('data');
import requests response = requests.post( "https://watchcron.com/api/v1/http-monitors", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "name": "Production Website", "url": "https://example.com", "method": "GET", "interval_seconds": 300, "timeout_seconds": 10, "expected_status_code": 200, "keyword": "Welcome", "ssl_check": True, "ssl_expiry_days_warn": 14, "grace_period_seconds": 60, "response_time_threshold_ms": 2000, }, ) monitor = response.json()["data"]
const response = await fetch("https://watchcron.com/api/v1/http-monitors", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ name: "Production Website", url: "https://example.com", method: "GET", interval_seconds: 300, timeout_seconds: 10, expected_status_code: 200, keyword: "Welcome", ssl_check: true, ssl_expiry_days_warn: 14, grace_period_seconds: 60, response_time_threshold_ms: 2000, }), }); const { data: monitor } = await response.json();
body := strings.NewReader(`{ "name": "Production Website", "url": "https://example.com", "method": "GET", "interval_seconds": 300, "timeout_seconds": 10, "expected_status_code": 200, "keyword": "Welcome", "ssl_check": true, "ssl_expiry_days_warn": 14, "grace_period_seconds": 60, "response_time_threshold_ms": 2000 }`) req, _ := http.NewRequest("POST", "https://watchcron.com/api/v1/http-monitors", body) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Response 201 Created
{
"data": {
"uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Production Website",
"url": "https://example.com",
"method": "GET",
"status": "new",
"interval_seconds": 300,
"timeout_seconds": 10,
"expected_status_code": 200,
"keyword": "Welcome",
"keyword_absent": false,
"grace_period_seconds": 60,
"response_time_threshold_ms": 2000,
"ssl_check": true,
"ssl_expiry_days_warn": 14,
"ssl_expiry_at": null,
"ssl_issuer": null,
"is_active": true,
"last_checked_at": null,
"last_response_time_ms": null,
"last_status_code": null,
"last_error": null,
"last_up_at": null,
"last_down_at": null,
"maintenance_windows": [],
"created_at": "2026-10-26T10:00:00Z",
"updated_at": "2026-10-26T10:00:00Z"
}
}
Validation errors
If the URL is invalid or a required field is missing, the API returns 422:
{
"message": "The url field must be a valid URL.",
"errors": {
"url": ["The url field must be a valid URL."]
}
}
Get an HTTP monitor
/api/v1/http-monitors/{uuid}
Returns full details for a single HTTP monitor.
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901"
$uuid = 'b2c3d4e5-f6a7-8901-bcde-f12345678901'; $response = Http::withToken('YOUR_API_KEY') ->get("https://watchcron.com/api/v1/http-monitors/{$uuid}"); $monitor = $response->json('data');
uuid = "b2c3d4e5-f6a7-8901-bcde-f12345678901" response = requests.get( f"https://watchcron.com/api/v1/http-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, ) monitor = response.json()["data"]
const uuid = "b2c3d4e5-f6a7-8901-bcde-f12345678901"; const response = await fetch( `https://watchcron.com/api/v1/http-monitors/${uuid}`, { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: monitor } = await response.json();
req, _ := http.NewRequest("GET", "https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901", nil) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Returns the same monitor object as shown in HTTP monitor object. Returns 404 if the UUID does not exist or belongs to a different project.
Update an HTTP monitor
/api/v1/http-monitors/{uuid}
Updates one or more fields on an existing HTTP monitor. Only include the fields you want to change — all fields are optional.
Request body
| Field | Type | Description |
|---|---|---|
name | string | Monitor name (max 255 characters) |
url | string | URL to monitor (max 2048 characters) |
method | string | HTTP method |
interval_seconds | integer | Check interval in seconds (min 30) |
timeout_seconds | integer | Request timeout in seconds (1–60) |
expected_status_code | integer|null | Expected HTTP status code (100–599) |
keyword | string|null | Keyword to search for in the response body |
keyword_absent | boolean | Whether to invert the keyword check |
grace_period_seconds | integer|null | Grace period before alerting |
response_time_threshold_ms | integer|null | Response time alert threshold in ms |
ssl_check | boolean | Enable/disable SSL monitoring |
ssl_expiry_days_warn | integer|null | Days before SSL expiry to warn |
headers | array|null | Custom request headers (replaces existing) |
http_auth_user | string|null | HTTP Basic Auth username |
http_auth_pass | string|null | HTTP Basic Auth password |
maintenance_windows | array|null | Maintenance windows (replaces existing) |
curl -X PUT https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "interval_seconds": 60, "timeout_seconds": 15, "keyword": "Dashboard", "response_time_threshold_ms": 3000 }'
$response = Http::withToken('YOUR_API_KEY') ->put("https://watchcron.com/api/v1/http-monitors/{$uuid}", [ 'interval_seconds' => 60, 'timeout_seconds' => 15, 'keyword' => 'Dashboard', 'response_time_threshold_ms' => 3000, ]);
response = requests.put( f"https://watchcron.com/api/v1/http-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "interval_seconds": 60, "timeout_seconds": 15, "keyword": "Dashboard", "response_time_threshold_ms": 3000, }, )
const response = await fetch(`https://watchcron.com/api/v1/http-monitors/${uuid}`, { method: "PUT", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ interval_seconds: 60, timeout_seconds: 15, keyword: "Dashboard", response_time_threshold_ms: 3000, }), });
body := strings.NewReader(`{ "interval_seconds": 60, "timeout_seconds": 15, "keyword": "Dashboard", "response_time_threshold_ms": 3000 }`) req, _ := http.NewRequest("PUT", "https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901", body) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Returns 200 OK with the updated monitor object.
"headers": [...] replaces all existing custom headers. Send "headers": null to clear them. The same applies to maintenance_windows.Delete an HTTP monitor
/api/v1/http-monitors/{uuid}
Permanently deletes an HTTP monitor and all its associated check logs.
curl -X DELETE \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901"
$response = Http::withToken('YOUR_API_KEY') ->delete("https://watchcron.com/api/v1/http-monitors/{$uuid}");
response = requests.delete( f"https://watchcron.com/api/v1/http-monitors/{uuid}", headers={"Authorization": "Bearer YOUR_API_KEY"}, )
const response = await fetch( `https://watchcron.com/api/v1/http-monitors/${uuid}`, { method: "DELETE", headers: { "Authorization": "Bearer YOUR_API_KEY" }, } );
req, _ := http.NewRequest("DELETE", "https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901", nil) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Returns 204 No Content on success. This action is irreversible.
Pause or unpause an HTTP monitor
/api/v1/http-monitors/{uuid}/pause
Pauses or unpauses an HTTP monitor. While paused, no checks are performed and no alerts are sent.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
paused | boolean | Yes | true to pause, false to unpause |
curl -X PATCH https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901/pause \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"paused": true}'
$response = Http::withToken('YOUR_API_KEY') ->patch("https://watchcron.com/api/v1/http-monitors/{$uuid}/pause", [ 'paused' => true, ]);
response = requests.patch( f"https://watchcron.com/api/v1/http-monitors/{uuid}/pause", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={"paused": True}, )
const response = await fetch( `https://watchcron.com/api/v1/http-monitors/${uuid}/pause`, { method: "PATCH", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ paused: true }), } );
body := strings.NewReader(`{"paused": true}`) req, _ := http.NewRequest("PATCH", "https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901/pause", body) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Returns 200 OK with the updated monitor object. To resume monitoring, send the same request with {"paused": false}.
List check logs
/api/v1/http-monitors/{uuid}/logs
Returns a paginated list of check log entries for an HTTP monitor, ordered from newest to oldest.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
per_page | integer | 25 | Results per page |
page | integer | 1 | Page number |
curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901/logs?per_page=10"
$response = Http::withToken('YOUR_API_KEY') ->get("https://watchcron.com/api/v1/http-monitors/{$uuid}/logs", [ 'per_page' => 10, ]); $logs = $response->json('data');
response = requests.get( f"https://watchcron.com/api/v1/http-monitors/{uuid}/logs", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"per_page": 10}, ) logs = response.json()["data"]
const response = await fetch( `https://watchcron.com/api/v1/http-monitors/${uuid}/logs?per_page=10`, { headers: { "Authorization": "Bearer YOUR_API_KEY" } } ); const { data: logs } = await response.json();
req, _ := http.NewRequest("GET", "https://watchcron.com/api/v1/http-monitors/b2c3d4e5-f6a7-8901-bcde-f12345678901/logs?per_page=10", nil) req.Header.Set("Authorization", "Bearer YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close()
Response 200 OK
{
"data": [
{
"status": "up",
"status_code": 200,
"response_time_ms": 187,
"error": null,
"checked_at": "2026-10-26T12:05:00Z"
},
{
"status": "up",
"status_code": 200,
"response_time_ms": 203,
"error": null,
"checked_at": "2026-10-26T12:00:00Z"
},
{
"status": "down",
"status_code": 503,
"response_time_ms": 5012,
"error": "Expected status 200, got 503",
"checked_at": "2026-10-26T11:55:00Z"
}
],
"meta": {
"pagination": {
"total": 8640,
"per_page": 10,
"current_page": 1,
"last_page": 864
}
}
}
Log entry fields
| Field | Type | Description |
|---|---|---|
status | string | Result of the check: up or down |
status_code | integer|null | HTTP status code returned by the URL (null if the request timed out or failed to connect) |
response_time_ms | integer|null | Response time in milliseconds |
error | string|null | Error description (null if the check passed) |
checked_at | string | ISO 8601 timestamp of when the check was performed |