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

  1. Set up the first request as usual: URL, method, headers, body and Checks.
  2. Under Steps, click Add step. Each step has a name, its own request and its own checks.
  3. 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+)).
  4. Use it in a later step, e.g. a header Authorization: Bearer {{token}} or a URL https://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:

Multi-step check config
{
  "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.