Monitors API
Monitors are the core of PixoMonitor. They periodically check your services and report on their availability and performance.
All monitor endpoints require authentication. Include the Authorization: Bearer {token} header with all requests.
Monitor Types
PixoMonitor supports the following monitor types:
| Type | Description |
|---|---|
HTTP | HTTP request monitoring |
HTTPS | HTTPS request monitoring with SSL verification |
TCP | TCP port connectivity check |
DNS | DNS record lookup monitoring |
SSL | SSL certificate expiration monitoring |
HEARTBEAT | Receives pings from your application |
DOMAIN | Domain expiration monitoring |
TRANSACTION | Multi-step browser transaction monitoring |
CRON | Cron job execution monitoring |
WEBSOCKET | WebSocket connection monitoring |
List Monitors
/api/monitorsRetrieve all monitors for the authenticated user
Headers:
| Header | Value |
|---|---|
| Authorization | Bearer {access_token} |
Success Response (200 OK):
{
"monitors": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"user_id": "user-uuid",
"name": "Production API",
"url": "https://api.example.com/health",
"type": "HTTPS",
"interval": 60,
"timeout": 10,
"status": "ACTIVE",
"component_id": null,
"heartbeat_interval": null,
"alert_cooldown_minutes": 5,
"expected_json_path": null,
"expected_json_value": null,
"domain_expiry_warn_days": null,
"anomaly_detection_enabled": false,
"anomaly_sensitivity": 2.0,
"check_locations_enabled": false,
"failure_threshold": 1,
"escalation_policy_id": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"last_status": "UP",
"last_response_time": 145,
"down_count": 3
}
]
}Create Monitor
/api/monitorsCreate a new monitor
Headers:
| Header | Value |
|---|---|
| Authorization | Bearer {access_token} |
| Content-Type | application/json |
Common Fields (All Monitor Types)
| Field | Type | Required | Default | Validation |
|---|---|---|---|---|
name | string | Yes | - | 1-100 characters |
type | string | Yes | - | See monitor types above |
url | string | Conditional | - | Valid URL (required for most types) |
interval | integer | No | 60 | 30-300 seconds |
timeout | integer | No | 10 | 5-30 seconds |
component_id | UUID | No | null | Link to status page component |
alert_cooldown_minutes | integer | No | 5 | 1-60 minutes |
anomaly_detection_enabled | boolean | No | false | Enable response time anomaly detection |
anomaly_sensitivity | float | No | 2.0 | 1.0-5.0 (standard deviations) |
check_locations_enabled | boolean | No | false | Enable multi-location checks |
failure_threshold | integer | No | 1 | Number of selected check locations that must fail before alerting (1-10) |
escalation_policy_id | UUID | No | null | Link to escalation policy |
check_location_ids | array | No | [] | Array of location UUIDs |
recurring_alert_window | object or null | No | null | Weekly alert grace for pull checks; null disables it (see below) |
recurring_alert_window example: {"days":[5],"start":"13:00","end":"17:00","timezone":"America/New_York","grace_minutes":5}. days contains unique weekday numbers (Sunday 0 through Saturday 6) on which the window starts; times are local HH:mm values and must differ. An end earlier than the start runs into the next day. Use a valid IANA time zone and 1–30 whole grace minutes. HEARTBEAT and CRON monitors do not support this setting. Checks and status history continue; a continuously DOWN monitor opens an incident after the grace period at its next scheduled check. If still DOWN when the window ends, the next check applies normal incident rules. Existing incidents are not silenced. Send null to disable the schedule. This does not change the request timeout or one-time maintenance windows.
Type-Specific Fields
HTTP/HTTPS Monitors
| Field | Type | Description |
|---|---|---|
expected_json_path | string | JSONPath to validate response (max 500 chars) |
expected_json_value | string | Expected value at JSONPath (max 500 chars) |
HEARTBEAT Monitors
| Field | Type | Validation | Description |
|---|---|---|---|
heartbeat_interval | integer | 30-86400 seconds | Expected interval between heartbeats |
HEARTBEAT monitors do not require a URL. A unique heartbeat_token is auto-generated and returned in the response.
DOMAIN Monitors
| Field | Type | Default | Description |
|---|---|---|---|
domain_expiry_warn_days | integer | 30 | Days before expiry to warn (1-365) |
CRON Monitors
| Field | Type | Required | Description |
|---|---|---|---|
expected_cron_expression | string | Yes | Cron expression (max 100 chars) |
grace_period_seconds | integer | No | Grace period after expected run (60-86400, default 300) |
WEBSOCKET Monitors
| Field | Type | Description |
|---|---|---|
ws_send_message | string | Message to send after connection (max 1000 chars) |
ws_expected_response | string | Expected response message (max 1000 chars) |
WebSocket URLs must start with ws:// or wss://.
Request Examples
HTTP Monitor:
{
"name": "Production API",
"type": "HTTPS",
"url": "https://api.example.com/health",
"interval": 60,
"timeout": 10,
"failure_threshold": 3,
"expected_json_path": "$.status",
"expected_json_value": "healthy"
}Heartbeat Monitor:
{
"name": "Backup Job",
"type": "HEARTBEAT",
"heartbeat_interval": 3600,
"alert_cooldown_minutes": 15
}Cron Monitor:
{
"name": "Daily Report Job",
"type": "CRON",
"expected_cron_expression": "0 0 * * *",
"grace_period_seconds": 600
}WebSocket Monitor:
{
"name": "Real-time Feed",
"type": "WEBSOCKET",
"url": "wss://stream.example.com/feed",
"ws_send_message": "{\"action\": \"ping\"}",
"ws_expected_response": "{\"action\": \"pong\"}"
}Success Response (201 Created):
{
"monitor": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"user_id": "user-uuid",
"name": "Production API",
"url": "https://api.example.com/health",
"type": "HTTPS",
"interval": 60,
"timeout": 10,
"status": "ACTIVE",
"heartbeat_token": null,
"created_at": "2024-01-15T10:30:00Z",
...
}
}Heartbeat Monitor Response (includes token):
{
"monitor": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Backup Job",
"type": "HEARTBEAT",
"heartbeat_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
...
}
}Get Monitor
/api/monitors/:idRetrieve a single monitor by ID
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Success Response (200 OK):
{
"monitor": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Production API",
"url": "https://api.example.com/health",
"type": "HTTPS",
"interval": 60,
"timeout": 10,
"status": "ACTIVE",
"last_status": "UP",
"last_response_time": 145,
"last_status_code": 200,
...
}
}Update Monitor
/api/monitors/:idUpdate an existing monitor
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
All fields from create are optional for updates. Additionally:
| Field | Type | Description |
|---|---|---|
regenerate_heartbeat_token | boolean | Generate new heartbeat token (HEARTBEAT type only) |
Request Example:
{
"name": "Production API v2",
"interval": 30,
"failure_threshold": 5
}Success Response (200 OK):
{
"monitor": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Production API v2",
"interval": 30,
"failure_threshold": 5,
"updated_at": "2024-01-16T14:20:00Z",
...
}
}Delete Monitor
/api/monitors/:idDelete a monitor and all its check history
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Success Response (200 OK):
{
"message": "Monitor deleted"
}Pause Monitor
/api/monitors/:id/pausePause monitoring (stops all checks)
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Success Response (200 OK):
{
"monitor": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "PAUSED",
...
}
}Resume Monitor
/api/monitors/:id/resumeResume a paused monitor
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Success Response (200 OK):
{
"monitor": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "ACTIVE",
...
}
}Get Check History
/api/monitors/:id/checksRetrieve check history for a monitor
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
limit | integer | 50 | Results per page (max 5000) |
start_date | ISO 8601 | - | Start of date range |
end_date | ISO 8601 | - | End of date range |
For date ranges over 48 hours, data is automatically aggregated into time buckets (15 min, 1 hour, or 6 hours depending on range) to improve performance.
Success Response (200 OK):
{
"checks": [
{
"id": "check-uuid",
"monitor_id": "monitor-uuid",
"status": "UP",
"response_time": 145,
"status_code": 200,
"error_message": null,
"checked_at": "2024-01-15T10:31:00Z"
}
],
"aggregated": false,
"bucketInterval": null,
"pagination": {
"page": 1,
"limit": 50,
"total": 1440,
"pages": 29
}
}Aggregated Response (for large date ranges):
{
"checks": [
{
"checked_at": "2024-01-15T10:00:00Z",
"response_time": 142,
"status": "UP",
"check_count": 4,
"status_code": 200,
"error_message": null
}
],
"aggregated": true,
"bucketInterval": "15 minutes",
"pagination": { ... }
}Get Check Statistics
/api/monitors/:id/checks/statsGet uptime and performance statistics
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
start_date | ISO 8601 | 30 days ago | Start of date range |
end_date | ISO 8601 | now | End of date range |
Success Response (200 OK):
{
"stats": {
"uptime_percent": 99.95,
"avg_response_time": 142.5,
"min_response_time": 98,
"max_response_time": 892,
"p50": 135,
"p95": 245,
"p99": 456
}
}Get Downtime History
/api/monitors/:id/downtimesGet downtime periods for a monitor
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
start_date | ISO 8601 | 30 days ago | Start of date range |
end_date | ISO 8601 | now | End of date range |
Success Response (200 OK):
{
"downtimes": [
{
"started_at": "2024-01-14T08:15:00Z",
"ended_at": "2024-01-14T08:22:00Z",
"duration_seconds": 420,
"cause": "Connection timeout"
},
{
"started_at": "2024-01-15T14:30:00Z",
"ended_at": null,
"duration_seconds": 1800,
"cause": "HTTP 503 Service Unavailable"
}
]
}A null value for ended_at indicates the downtime is still ongoing.
Get Anomaly Detection Baseline
/api/monitors/:id/baselineGet the response time baseline for anomaly detection
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Success Response (200 OK) - Baseline Ready:
{
"baseline": {
"mean_response_time": 145.5,
"std_deviation": 25.3,
"p95_response_time": 198,
"sample_count": 500,
"calculated_at": "2024-01-15T10:00:00Z",
"threshold": 196.1
},
"collecting": false,
"anomaly_detection_enabled": true,
"anomaly_sensitivity": 2.0
}Response - Still Collecting Data:
{
"baseline": null,
"collecting": true,
"sample_count": 45,
"required_samples": 100,
"anomaly_detection_enabled": true,
"anomaly_sensitivity": 2.0
}Get Location Check Results
/api/monitors/:id/location-resultsGet multi-location check results
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | UUID | Monitor ID |
Success Response (200 OK):
{
"locationResults": [
{
"id": "result-uuid",
"check_id": "check-uuid",
"location_id": "location-uuid",
"location_name": "US East",
"location_region": "us-east-1",
"is_local": false,
"status": "UP",
"response_time": 145,
"status_code": 200,
"checked_at": "2024-01-15T10:30:00Z"
}
]
}Transaction Steps
Get Transaction Steps
/api/monitors/:id/transaction-stepsGet the steps for a transaction monitor
Success Response (200 OK):
{
"steps": [
{
"id": "step-uuid",
"monitor_id": "monitor-uuid",
"step_order": 1,
"action_type": "navigate",
"selector": null,
"value": "https://example.com/login",
"description": "Go to login page"
},
{
"id": "step-uuid-2",
"monitor_id": "monitor-uuid",
"step_order": 2,
"action_type": "type",
"selector": "#email",
"value": "test@example.com",
"description": "Enter email"
}
]
}Update Transaction Steps
/api/monitors/:id/transaction-stepsReplace all transaction steps
Valid Action Types:
| Action Type | Selector Required | Value Required | Description |
|---|---|---|---|
navigate | No | Yes (URL) | Navigate to URL |
click | Yes | No | Click an element |
type | Yes | Yes | Type text into input |
wait | No | Yes (ms) | Wait for duration |
assert_text | Yes | Yes | Assert element contains text |
assert_element | Yes | No | Assert element exists |
screenshot | No | No | Take a screenshot |
Request Example:
{
"steps": [
{
"action_type": "navigate",
"value": "https://example.com/login",
"description": "Go to login page"
},
{
"action_type": "type",
"selector": "#email",
"value": "test@example.com",
"description": "Enter email"
},
{
"action_type": "type",
"selector": "#password",
"value": "password123"
},
{
"action_type": "click",
"selector": "button[type='submit']"
},
{
"action_type": "wait",
"value": "2000"
},
{
"action_type": "assert_text",
"selector": ".welcome-message",
"value": "Welcome back"
}
]
}Validation Rules:
- Selectors: max 500 characters
- Values: max 2000 characters
navigaterequires a value (URL)clickandassert_elementrequire a selectortypeandassert_textrequire both selector and valuewaitrequires a numeric value (milliseconds)
Get Transaction Results
/api/monitors/checks/:checkId/transaction-resultsGet step-by-step results for a transaction check
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
checkId | UUID | Check ID |
Success Response (200 OK):
{
"results": [
{
"id": "result-uuid",
"check_id": "check-uuid",
"step_order": 1,
"action_type": "navigate",
"status": "passed",
"duration_ms": 1250,
"error_message": null,
"screenshot_url": null
},
{
"id": "result-uuid-2",
"check_id": "check-uuid",
"step_order": 2,
"action_type": "type",
"status": "passed",
"duration_ms": 45,
"error_message": null,
"screenshot_url": null
}
]
}Error Responses
| Status | Error | Description |
|---|---|---|
| 400 | Validation errors | Invalid request body |
| 400 | URL is required for this monitor type | Missing URL for HTTP/TCP/etc. |
| 400 | WebSocket URL must start with ws:// or wss:// | Invalid WebSocket URL |
| 400 | Cron expression is required for CRON type | Missing cron expression |
| 400 | Invalid cron expression format | Malformed cron expression |
| 404 | Monitor not found | Monitor doesn't exist or not owned by user |
| 500 | Failed to create/update/delete monitor | Server error |
