Test the response time of an API

Add a time budget to a step of a zriz pipeline. The step fails when the API needs more milliseconds than your limit.

Lesson 11 of 12 · zz 0.9.0 or later · Updated 2026-10-14 · Plain text for agents: /learn/test-api-response-time.md

The problem

An API can return the right data and still be too slow. A test of the status code does not see this. Users see it first.

The test

The example is a shop API. The health call must answer 200 in under 800 ms.

Start from a project that zz init made: the quick start gives the commands. The resource target already has the action check.

.zriz/resources/target.json:

{
  "type": "http",
  "description": "Your app under test",
  "base-url": "${env.TARGET_URL}",
  "headers": { "Content-Type": "application/json" },
  "actions": {
    "check": { "method": "GET", "path": "/api/health" }
  }
}

.zriz/pipelines/health-is-fast.json:

{
  "description": "The health call answers in under 800 ms",
  "steps": [
    {
      "call": "target/check",
      "expect": [
        ["status", "==", 200],
        ["timing.target-ms", "<", 800]
      ]
    }
  ]
}

Run it

zz run health-is-fast

"status":"pass"

What it proves

• timing.target-ms < 800: the API answered fast enough. A slow reply fails the step. The reason is assertion: timing.target-ms is 1130 and the pipeline expects 800.

• status == 200: the reply is the normal one. A step with only a time budget passes on a fast 500.

• The runner measures the number next to your API, in your network. A tool on your laptop shows a longer time, because it has the internet in it.

• The number is the time from the request to the end of the body. The time to open the connection is not in it.

Note: One call is one sample. Set the limit to three times the usual time, or more.

Next

• Test a database query for speed
• Pipelines gives each rule of the time budget, also for a repeat with poll.