OpenUptime

Multi-step API checks

An HTTP monitor can run up to 5 more requests after its own, in order, as one check. A later request can use a value an earlier answer returned, such as a login token or the id of a new record. The check passes only when every request passes.

How a run works

  1. The monitor's own request runs first, with its method, headers, body, expected status, keyword and JSON assertions. In results it is called Request 1.
  2. Each value listed under extract is read from that answer.
  3. Each step then runs in order. Every {{name}} in its URL, headers and body is replaced by the value read earlier, and the step's own expected status and JSON assertions must hold. A step can read more values for the steps after it.

The first request that fails ends the run. The error names it, for example Step 2 (List orders): Expected 200, got 401, and the incident shows each request with its status and time.

Define the steps

In the monitor form, open API steps under the HTTP settings and enter the steps as JSON. Through the API or the MCP server, send the same object as apiFlow when you create or update a monitor; "apiFlow": null removes the steps.

{
  "extract": [{ "name": "token", "from": "json", "path": "$.access_token" }],
  "steps": [
    {
      "name": "List orders",
      "method": "GET",
      "url": "https://api.example.com/v1/orders?limit=1",
      "headers": { "Authorization": "Bearer {{token}}" },
      "expectedStatus": 200,
      "jsonAssertions": [{ "path": "$.data", "op": "exists", "value": "" }],
      "extract": [{ "name": "orderId", "path": "$.data[0].id" }]
    },
    {
      "name": "Read one order",
      "method": "GET",
      "url": "https://api.example.com/v1/orders/{{orderId}}",
      "headers": { "Authorization": "Bearer {{token}}" }
    }
  ]
}
  • extract reads a value either from the JSON body ("from": "json", the default, with a path such as $.data.items[0].id) or from a response header ("from": "header", with the header name as the path). A name uses letters, digits and _, starts with a letter, and is read only once. Up to 10 per request.
  • A step has a name, a url, and optionally method (GET by default), headers, body, expectedStatus (200 by default), jsonAssertions (the same as the monitor's) and extract.
  • Every {{name}} a step uses must be read by an earlier request. Saving fails otherwise.
  • GET and HEAD steps cannot have a body. A body is up to 16 KiB.

What a value cannot change

A value read from an answer can go in a step's path, query, headers and body, but never in its host: where each request goes, and which headers it carries there, is fixed when the monitor is saved. Each step URL follows the same rules as the monitor's own address, so a private address is refused unless your installation allows private targets.

Secrets

Values read during a run are treated as secrets. They are removed from errors, the incident's diagnosis and alerts, together with the monitor's own header values. Step header values and bodies are masked for members who cannot manage monitors, like the monitor's own headers. Such a member can still save the form with the masked values left as they are, but cannot change a step's address or method while the steps hold hidden values.

Timeout, regions and billing

The monitor's timeout covers the whole run, not each request: if earlier requests use it up, the remaining steps do not run and the check fails as a timeout. The recorded latency is the time of the whole run. The monitor's interval, regions and alert settings apply to the run as a whole, and a run counts as one check in each region however many steps it has.

If you run your own probes, update them before adding steps to a monitor that is checked from them: an older probe refuses the check and its region shows as unreachable.

多步骤 API 检测

HTTP 监控可以在自身请求之后,再按顺序发出最多 5 个请求,合起来算作一次检测。后面的请求可以使用前面响应中返回的值,比如登录令牌或新建记录的 ID。只有所有请求都通过,检测才算通过。

一次检测怎样进行

  1. 先发出监控自身的请求,使用它的方法、请求头、请求体、期望状态码、关键词和 JSON 断言。结果中它叫作 Request 1。
  2. 从这次响应中读出 extract 列出的每个值。
  3. 然后依次执行每个步骤:URL、请求头和请求体中的 {{name}} 会被替换为之前读到的值,并且必须满足该步骤自己的期望状态码和 JSON 断言。步骤也可以为后续步骤读出新的值。

第一个失败的请求会终止这次检测。错误信息会写明是哪一步,例如 Step 2 (List orders): Expected 200, got 401;事件中会列出每个请求的状态码和耗时。

定义步骤

在监控表单的 HTTP 设置中展开 API 步骤,用 JSON 填写步骤。通过 API 或 MCP 服务创建或更新监控时,把同样的对象作为 apiFlow 发送即可;"apiFlow": null 会删除所有步骤。

{
  "extract": [{ "name": "token", "from": "json", "path": "$.access_token" }],
  "steps": [
    {
      "name": "List orders",
      "method": "GET",
      "url": "https://api.example.com/v1/orders?limit=1",
      "headers": { "Authorization": "Bearer {{token}}" },
      "expectedStatus": 200,
      "jsonAssertions": [{ "path": "$.data", "op": "exists", "value": "" }],
      "extract": [{ "name": "orderId", "path": "$.data[0].id" }]
    },
    {
      "name": "Read one order",
      "method": "GET",
      "url": "https://api.example.com/v1/orders/{{orderId}}",
      "headers": { "Authorization": "Bearer {{token}}" }
    }
  ]
}
  • extract 可以从 JSON 响应体读取("from": "json",默认值,路径形如 $.data.items[0].id),也可以从响应头读取("from": "header",路径填响应头名称)。名称由字母、数字和 _ 组成,以字母开头,每个名称只能读取一次。每个请求最多 10 个。
  • 每个步骤包含 name、url,以及可选的 method(默认 GET)、headers、body、expectedStatus(默认 200)、jsonAssertions(与监控自身的相同)和 extract。
  • 步骤中用到的每个 {{name}} 都必须由前面的请求读取,否则无法保存。
  • GET 和 HEAD 步骤不能带请求体。请求体最大 16 KiB。

读到的值不能改变什么

从响应中读到的值可以用在步骤的路径、查询参数、请求头和请求体中,但不能用在主机名中:每个请求发往哪里、带着哪些请求头,在保存监控时就已确定。每个步骤的 URL 都遵循与监控地址相同的规则,除非你的实例允许内网目标,否则内网地址会被拒绝。

敏感信息

检测过程中读到的值都按敏感信息处理,会和监控自身的请求头值一起,从错误信息、事件诊断和告警中移除。对没有监控管理权限的成员,步骤的请求头值和请求体会被遮盖,与监控自身的请求头相同。这类成员可以在不改动遮盖值的情况下保存表单,但当步骤中有隐藏的值时,不能修改步骤的地址或方法。

超时、区域与计费

监控的超时时间覆盖整次检测,而不是每个请求:如果前面的请求用完了时间,剩下的步骤不会执行,检测按超时判定失败。记录的延迟是整次检测的耗时。监控的检测间隔、区域和告警设置作用于整次检测;无论有多少步骤,一次检测在每个区域都只算一次。

如果你运行自己的探针,请先更新探针,再为由它们检测的监控添加步骤:旧版探针会拒绝这类检测,对应区域会显示为无法连通。

Last updated 2026-11-16最后更新:2026-11-16