How to Monitor API Endpoints: Health Checks, Assertions and Workflows

API monitoring means regularly sending real requests to your API from outside and verifying that the responses are correct, not just that the server answered. APIs fail in ways a homepage check never sees: a database error behind a cached frontend, an expired upstream token, a schema change that breaks mobile clients, or an authentication service that is down.

What to monitor

What a good /health endpoint returns

A good health endpoint answers one question: can this service do its job right now? It should check the dependencies the service cannot work without and return a clear status code.

GET /health

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "status": "ok",
  "version": "2026.10.1",
  "checks": {
    "database": "ok",
    "cache": "ok",
    "queue": "ok"
  }
}

Design rules:

• Return 200 when healthy and 503 when a critical dependency is down, so monitors can rely on the status code alone.
• Run a real but cheap query against each critical dependency, such as SELECT 1, with a short timeout.
• Respond quickly, well under a second, and never call slow external APIs synchronously.
• Send Cache-Control: no-store and bypass CDN caching, or you will be monitoring a cached response.
• Do not expose secrets, hostnames, stack traces or detailed version information on a public endpoint.
• Separate liveness (the process is running) from readiness (it can serve traffic). External monitors should use readiness.
• Decide which dependencies are critical. If a non-critical one fails, report "degraded" but still return 200.

Assertions: checking more than the status code

A 200 response with an empty array or an error object inside is still a failure from the client's point of view. Use assertions:

• Status code: exact (200) or range (2xx).
• Response time: alert when the endpoint becomes unusably slow.
• Substring: the body contains "status":"ok".
• Regex: a field matches a pattern, such as a version string.
• JSONPath: $.status equals ok, or $.items is not empty.
• Header: content type is application/json.

Keep assertions on fields that are stable. Asserting on timestamps, counts or other changing values creates false alerts.

Authentication and secrets

Many endpoints require credentials. Monitor them safely:

1. Create a dedicated, read-only API key or service account for monitoring. Never use a personal or admin token.
2. Store it as an encrypted secret in the monitoring tool and reference it from the Authorization header, rather than pasting it into URLs where it can end up in logs.
3. Scope the account to a test tenant or test data where possible.
4. Rotate the key on a schedule, and update the monitor at the same time.

GET /v1/orders?limit=1
Host: api.example.com
Authorization: Bearer {{secret:monitoring_token}}
Accept: application/json

The placeholder syntax differs between tools; the principle is the same.

Avoid side effects

A monitor that runs every minute sends more than 40,000 requests a month, so every side effect is multiplied. Do not monitor endpoints that create orders, charge cards, send emails or write data, unless they are designed for it (for example, a sandbox that discards writes). Prefer GET requests. If you must test a write path, use a dedicated test account and an endpoint that cleans up after itself.

Multi-step API checks

Some failures only show up across several calls. A multi-step check, also called an API workflow or transaction check, runs requests in sequence and passes values between them:

1. POST /auth/token with test credentials; extract access_token from the response.
2. GET /v1/me with the token; assert the account ID matches.
3. GET /v1/projects; assert the list is not empty.

This catches broken token issuance, permission errors and data-layer problems that individual checks miss.

API monitoring in Uptime Tracker

Uptime Tracker covers APIs at several levels. Basic HTTP(S) checks on every plan assert on status codes and keywords and record a DNS, connect, TLS and time-to-first-byte breakdown. Advanced HTTP checks (Starter and above) support any method, custom headers, request bodies up to 64 KiB, encrypted secrets referenced from headers (dropped on cross-origin redirects), and substring, RE2 regex and JSONPath assertions; the editor warns about methods with side effects. The Team plan adds API workflows of up to 10 chained requests that pass extracted values such as auth tokens between steps, plus gRPC health checks. See API monitoring.

Interpreting failures

Checklist

• A readiness-style /health endpoint that checks critical dependencies and returns 200 or 503.
• Monitors on the health endpoint and the most important real endpoints.
• Assertions on status, response time and stable JSON fields.
• A read-only monitoring token stored as an encrypted secret.
• No monitors on endpoints with side effects.
• A multi-step check for authentication flows.
• Alerts routed by severity; see reducing false positives.