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

GET/api/monitors

Retrieve 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

POST/api/monitors

Create 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	1-10 consecutive failures before alert
`escalation_policy_id`	UUID	No	null	Link to escalation policy
`check_location_ids`	array	No	[]	Array of location UUIDs

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

GET/api/monitors/:id

Retrieve 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

PUT/api/monitors/:id

Update 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

DELETE/api/monitors/:id

Delete 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

POST/api/monitors/:id/pause

Pause 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

POST/api/monitors/:id/resume

Resume 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

GET/api/monitors/:id/checks

Retrieve 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

GET/api/monitors/:id/checks/stats

Get 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

GET/api/monitors/:id/downtimes

Get 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

GET/api/monitors/:id/baseline

Get 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

GET/api/monitors/:id/location-results

Get 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

GET/api/monitors/:id/transaction-steps

Get 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

PUT/api/monitors/:id/transaction-steps

Replace 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
navigate requires a value (URL)
click and assert_element require a selector
type and assert_text require both selector and value
wait requires a numeric value (milliseconds)

Get Transaction Results

GET/api/monitors/checks/:checkId/transaction-results

Get 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