A MongoDB-style query language for defining exactly when a monitor is up or down.
-
-
-
Overview
-
A PingQL query is a JSON object that runs against every ping result. If the query evaluates to true, the monitor is considered up. Use $consider: "down" to invert this.
-
By default (no query set), a monitor is up when the HTTP status code is below 400.
-
-
-
Fields
-
These are the values you can query against:
-
-
Field
Type
Description
-
-
status
number
HTTP status code (e.g. 200, 404)
-
body
string
Full response body as text
-
headers.name
string
Response header value (e.g. headers.content-type)
-
$responseTime
number
Request latency in milliseconds
-
$certExpiry
number
Days until SSL certificate expires
-
$json
object
JSONPath expression against response body — see below
-
$select
object
CSS selector against response HTML — see below
-
-
-
-
-
Operators
-
-
Operator
Description
Types
-
-
$eq
Equal to
any
-
$ne
Not equal to
any
-
$gt
Greater than
number
-
$gte
Greater than or equal
number
-
$lt
Less than
number
-
$lte
Less than or equal
number
-
$contains
String contains substring
string
-
$startsWith
String starts with
string
-
$endsWith
String ends with
string
-
$regex
Matches regular expression
string
-
$exists
Field is present and non-null
any
-
$in
Value is in array
any
-
-
-
-
-
Basic Examples
-
-
Status code
-
// Up if status is 200
-{ "status": 200 }
-
-// Up if status is 2xx or 3xx
-{ "status": { "$lt": 400 } }
-
-
Response body
-
// Up if body contains "healthy"
-{ "body": { "$contains": "healthy" } }
-
-// Up if body matches a regex
-{ "body": { "$regex": "status.*(ok|healthy)" } }
-
-
Headers
-
// Up if response is JSON
-{ "headers.content-type": { "$contains": "application/json" } }
-
-
Response time
-
// Up if response is under 500ms
-{ "$responseTime": { "$lt": 500 } }
-
-
SSL certificate expiry
-
// Up if cert expires in more than 14 days
-{ "$certExpiry": { "$gt": 14 } }
-
-
-
JSON Body — $json
-
Use $json to extract and compare a value from a JSON response body. The key is a dot-notation path, the value is a condition.
-
// Up if response JSON has { "status": "ok" }
-{ "$json": { "$.status": { "$eq": "ok" } } }
-
-// Up if search index has >= 1000 entries
-{ "$json": { "$.data.count": { "$gte": 1000 } } }
-
-// Nested path
-{ "$json": { "$.db.connections.active": { "$lt": 100 } } }
-
-
-
HTML Parsing — $select
-
Use $select to extract text from an HTML response using a CSS selector. Useful for monitoring public-facing pages where there's no API.
-
// Up if h1 text is "Example Domain"
-{ "$select": { "h1": { "$eq": "Example Domain" } } }
-
-// Up if status badge contains "operational"
-{ "$select": { ".status-badge": { "$contains": "operational" } } }
-
-
-
Logical Operators
-
// Up if status is 200 AND body contains "ok"
-{
- "$and": [
- { "status": 200 },
- { "body": { "$contains": "ok" } }
- ]
-}
-
-// Up if status is 200 OR 204
-{
- "$or": [
- { "status": 200 },
- { "status": 204 }
- ]
-}
-
-// Up if status is NOT 500
-{ "$not": { "status": 500 } }
-
-
-
$consider — Inverting the Result
-
By default, a query returning true means the monitor is up. Set $consider: "down" to invert this — if the conditions match, the monitor is down.
-
// DOWN if response time exceeds 2 seconds
-{
- "$consider": "down",
- "$responseTime": { "$gt": 2000 }
-}
-
-// DOWN if cert expires in less than 7 days
-{
- "$consider": "down",
- "$certExpiry": { "$lt": 7 }
-}
-
-// DOWN if any of these match
-{
- "$consider": "down",
- "$or": [
- { "status": { "$gte": 500 } },
- { "$responseTime": { "$gt": 5000 } }
- ]
-}
-
-
-
Combining Multiple Queries
-
You can add multiple monitors pointing to the same URL with different queries — one for uptime, one for performance, one for content integrity.
PingQL is a developer-friendly uptime monitoring API. Monitors are defined with a URL, an interval, and an optional query that determines what "up" means for your service.
+
Base URL: https://api.pingql.com
+
+
+
+
+
Authentication
+
All API requests require an account key passed as a Bearer token:
+
+
http
+
Authorization: Bearer XXXX-XXXX-XXXX-XXXX
+
+
Create an account at /dashboard or via the API. Keys are 16-character hex strings formatted as four groups.
+
+
+
+
+
Account
+
+
Register
+
POST/account/register
+
Create a new account. Email is optional — used only for recovery and alerts.
Extract text content from an HTML response using a CSS selector. Useful for monitoring public pages without an API.
+
+
json
+
// matches if <h1> text is exactly "Example Domain"
+{ "$select": { "h1": { "$eq": "Example Domain" } } }
+
+// matches if status badge contains "operational"
+{ "$select": { ".status-badge": { "$contains": "operational" } } }
+
+
+
+
+
+
Logical Operators
+
+
json
+
// $and — all conditions must match
+{ "$and": [{ "status": 200 }, { "body": { "$contains": "ok" } }] }
+
+// $or — any condition must match
+{ "$or": [{ "status": 200 }, { "status": 204 }] }
+
+// $not — invert a condition
+{ "$not": { "status": 500 } }
+
+
+
+
+
+
$consider
+
By default, matching conditions mean the monitor is up. Set "$consider": "down" to flip this — if the conditions match, the monitor is down.
+
+
json
+
// down if response time exceeds 2 seconds
+{ "$consider": "down", "$responseTime": { "$gt": 2000 } }
+
+// down if cert expires in less than 7 days
+{ "$consider": "down", "$certExpiry": { "$lt": 7 } }
+
+// down if any of these match
+{
+ "$consider": "down",
+ "$or": [
+ { "status": { "$gte": 500 } },
+ { "$responseTime": { "$gt": 5000 } }
+ ]
+}