Healthchecks
Multi-step API Checks
Run several requests in a row and pass values between them.
Overview
Some failures only show up in a flow: the login endpoint answers, but the token it returns doesn't work on the next call. A multi-step API check is an HTTP check with more than one request. A step can save values from its response, such as a token or an id, and later steps use them as {{name}} in their URL, headers or body.
Multi-step API checks are a plan feature. On a plan without them, Add step is locked; after a downgrade, existing multi-step checks stop running until you upgrade or remove their later steps.
Adding steps
- Set up the first request as usual: URL, method, headers, body and Checks.
- Under Steps, click Add step. Each step has a name, its own request and its own checks.
- In Values to save for later steps, name a value and say where it comes from: a JSON field (
access_token), a header (X-Request-Id) or a regex with a capture group on the body (id=(\d+)). - Use it in a later step, e.g. a header
Authorization: Bearer {{token}}or a URLhttps://api.example.com/users/{{userId}}.
A check can have up to 10 steps. Steps can be reordered and removed.
How a run works
- Steps run in order, and the run stops at the first step that fails.
- Cookies a response sets are sent with the later steps, so sessions carry over.
- Every request is checked against the same rules as a single HTTP check, after its values are filled in: a value from a response can't point a later step at a private address.
- The check's timeout covers the whole run. Each step is timed on its own in the results.
Saved values stay private
Saved values, such as tokens, are replaced with *** in check results, logs and error messages. Credentials you type into a step's headers or body are stored with the check, the same as for a single HTTP check.
Results
A result lists each step that ran, with its status code, time and, for the step that failed, why. An incident names the failed step, for example step 2 "orders": status code 401 (expected below 400).
Config
Through the API or uptimyctl, a multi-step check is a list of steps:
{
"steps": [
{
"name": "login",
"request": {
"method": "POST",
"uri": "https://api.example.com/login",
"body": { "user": "monitor", "password": "..." }
},
"assertions": [{ "source": "status", "op": "eq", "value": 200 }],
"extract": [{ "var": "token", "source": "json", "path": "access_token" }]
},
{
"name": "orders",
"request": {
"method": "GET",
"uri": "https://api.example.com/orders",
"headers": { "Authorization": "Bearer {{token}}" }
},
"assertions": [{ "source": "json", "path": "orders", "op": "exists" }]
}
]
}extract takes json (with path), header (with name) or regex (with pattern). Value names use letters, digits and _, and can't start with secret.