Advanced API Monitoring with JSONPath

When monitoring APIs, sometimes checking the HTTP status code isn’t enough. You might need to verify that specific data is present in the response body or that values meet certain criteria. StatusPage.me supports JSONPath for deep inspection of JSON responses.

Last updated: 2026-06-12

What is JSONPath?

JSONPath is a query language for JSON, similar to how XPath is used for XML. It allows you to select specific parts of a JSON structure using a path expression.

Using JSONPath in Monitors

When creating or editing an API Monitor:

1. If needed, open Advanced Request Settings and configure the method, query parameters, headers, or request body you want to send.
2. Open Validation in the Add/Edit Monitor form.
3. Add a new condition row.
4. Select JSON Path as the target.
5. Enter your JSONPath expression in the path field (usually starting with $.).
6. Choose an operator (e.g., equals, contains, matches).
7. Enter the expected value.

If you choose POST, PUT, or PATCH, the form shows a helper below HTTP Method that opens Advanced Request Settings directly.

You can combine multiple checks with ALL (AND) / ANY (OR) logic (for example: JSONPath + status code + response time).

Guide: Advanced Expected Conditions

Importing Conditions from a Live Response

📹 Video walkthrough coming soon — this section will embed a short demo of the auto-detect import flow.

Instead of writing JSONPath expressions by hand or copying and pasting raw JSON, the dashboard can fetch a live response from your endpoint and let you pick the fields you want to monitor in a visual picker.

Auto-detect (recommended)

When you enter an API endpoint in the monitor form, the dashboard fetches a live response in the background — the same probe that validates your URL. If the response is JSON, a ✓ Response detected hint appears next to the Import from JSON button.

Click Import from JSON to open the Auto-detected JSON Structure picker. No copy-pasting needed.

If no response was detected — because the endpoint requires authentication, returns non-JSON, or the URL hasn’t been probed yet — the button falls back to the manual paste flow described below.

What the picker shows

Fields are grouped by their parent key. Root-level fields appear under ROOT; nested fields appear under their parent name (e.g. COMPONENTS).

Each row shows:

• The field name (or item identifier for array entries) in plain language
• A value badge coloured by type: grey for strings, green for true, red for false, blue for numbers
• The full JSONPath expression in small monospace text, so you can verify exactly what will be checked

Common field names — status, code, error, message, ok, result, state, healthy, alive — are pre-checked. Everything else starts unchecked. Toggle the fields you want, then click Import Selected. The conditions are added to the Validation section immediately.

Arrays with a unique identifier (key, id, slug, or code) are expanded automatically — one row per item — using filter expressions, not fragile index-based paths. The identifier field and display-name fields (label, name, title) are omitted since they are not useful as health conditions.

Example: given this response:

{
  "components": [
    { "key": "api",     "label": "API",     "status": "ok" },
    { "key": "billing", "label": "Billing", "status": "ok" },
    { "key": "upload",  "label": "Upload",  "status": "ok" }
  ]
}

The picker shows a COMPONENTS group with three rows — api, billing, and upload — each representing:

$.components[?(@.key=='api')].status     = ok
$.components[?(@.key=='billing')].status = ok
$.components[?(@.key=='upload')].status  = ok

These filter expressions remain correct even if the array order changes.

Already-monitored conditions are hidden. If another monitor already checks $.components[?(@.key=='api')].status for the same URL, that row is omitted and a note shows: “N condition(s) hidden — already monitored at this URL.” This prevents duplicate checks when you create multiple monitors for the same endpoint.

Manual paste (fallback)

If your endpoint requires authentication or you want to import conditions from a specific response payload that differs from the live response, click Paste custom output instead → in the picker (or use it directly when no live response is available):

1. Click Import from JSON in the Validation section.
2. Paste your API’s JSON response into the text area.
3. Click Generate Conditions.

The same smart traversal applies: filter expressions for identified arrays, label/name fields skipped, already-monitored conditions hidden.

Reading Condition Paths

JSONPath conditions in the condition builder display as depth-coloured badge pills instead of raw text. Each segment of the path gets a distinct colour based on its depth in the JSON tree, making it easy to scan complex nested paths at a glance.

Click any pill row to switch to raw text edit mode; press Enter or click away to return to pills.

Syntax Basics

Our JSONPath implementation supports standard syntax:

• $ : The root object/element
• . or [] : Child operator
• * : Wildcard
• n:s : Array slice

Examples

Consider this JSON response from a payment API:

{
  "status": "success",
  "data": {
    "balance": 500,
    "currency": "USD",
    "transactions": [
      { "id": 1, "state": "completed" },
      { "id": 2, "state": "pending" }
    ]
  },
  "maintenance": false
}

Troubleshooting

• Case Sensitivity: JSON keys and values are case-sensitive.

• Path Validity: Ensure your path starts with $ to reference the root.

• Numbers vs Strings: When comparing numbers, ensure you select numerical operators like gte (greater than or equal) or lte if available, though strict equality works for string representations in many cases.

• Success vs Failure: Advanced expected conditions describe what counts as UP. If your conditions don’t match, the monitor is marked DOWN.

  • Example: $.status not_contains ok only matches when status is not ok.
  • Example: To alert on slow responses (>45s), configure response time as an UP condition like lt 45000.

For complex paths, we recommend testing your JSONPath expression against your API response using online tools before configuring your monitor.