Skip to main content
An API metric check fetches a JSON API on your interval, extracts a value with a value path, and evaluates it against a condition. The extracted value is stored on every run, so the check’s overview graphs it over time — you get a usage/spend chart for free, plus alerts when it crosses your threshold.

​
How it works

  1. Alertee requests your url (with any headers and body you configure).
  2. The response must be JSON; the value_path picks the metric out of it.
  3. The value flows through the same condition engine as a SQL single-value check: greater_than, less_than, between, equals, and the rest.
  4. Each run’s value is recorded — open the check to see the trend chart.
With no condition, the check simply verifies the API responds and the value extracts — useful while you’re exploring an API.

​
Value paths

Value paths use gjson syntax: dot-separated keys with numeric array indexes.

​
Grid metrics

If the path yields an array of {name, value} objects, the check becomes a grid check — one cell per dimension, with evaluation_type conditions like all_cells and dimension_missing. Reshape arbitrary arrays with gjson aliasing:
turns {"days": [{"date": "2026-06-10", "minutes": 10}, …]} into one cell per day.

​
Authentication

Put your API token in a request header:
Use a scoped, read-only token where the provider supports it, and rotate it like any other credential. Header values are masked everywhere they’re read back — the app, the CLI, and the MCP get_check/list_checks all show •••••• instead of the token. Editing a check preserves the stored token; the mask is never saved over it. (If you save a header whose value is literally the •••••• placeholder — e.g. an agent that only ever saw the masked value — the write is rejected so a real token is never silently replaced. Pass the real token.)

​
Query parameters (HTTP-SQL, Tinybird)

Some APIs — Tinybird and other HTTP-SQL endpoints — take their input as a URL query parameter, e.g. a SQL statement in ?q=…. Pass these as query_params and Alertee URL-encodes them for you, so you never hand-encode a query string:
Tinybird returns { "data": [ { "value": 1234 } ] }, so data.0.value extracts the count. For a per-dimension (grid) check, alias the data array into {name,value} rows with a value path like data.#.{name:dimension,value:metric}.

​
Example: alert when cloud spend runs away

Say your provider exposes a usage endpoint that returns month-to-date consumption. To alert before the bill surprises you:
The condition describes the healthy state — here, under 50,000 minutes this month. The check alerts once usage crosses it, and the overview chart shows the month’s burn as it accumulates. The same pattern works for any JSON API: SaaS usage and billing endpoints, queue depths, error counters, your own internal admin APIs.
Connect/gRPC-style APIs work too — they accept JSON over POST (hence --http-method POST --request-body '{}') and respond with proto3 JSON, where field names are camelCase and large integers arrive as strings. Alertee converts numeric strings to numbers automatically, so conditions and the chart behave as expected.

​
Configuration reference

Available from the app (check type “API metric”), the CLI (--type api_metric), and the MCP server (create_check with check_type: "api_metric").

​
Previewing the response

Before saving, probe the endpoint to see its shape and the paths you can extract — no need to curl first. It runs the request and lists every gjson leaf path:
Pass --value-path to confirm exactly what a path extracts. The same capability is the MCP preview_api_metric tool — handy when an agent is authoring a check.