Heartbeat URL retrieval and ingestion

Retrieve URLs

GET /api/v1/checks/:id/ping_urls / MCP get_check_ping_urls. Requires checks:ping_urls, current operational-credential permission and a heartbeat check. Other kinds return invalid_kind.

{
  "id": "check_EXAMPLE",
  "sensitive": true,
  "locations": [
    {
      "name": "default",
      "url": "https://pingstack.io/ping/LOCATION_TOKEN"
    }
  ]
}

Never display a real result in an AI conversation, public log or source file. The URL grants reporting access. Ordinary check reads do not disclose it.

Send a heartbeat

GET or POST the location URL. Ingestion uses the URL’s token, not the automation bearer token. These are separate credential types.

Input	Behavior
Location token in path	Required; unknown token returns 404
value query parameter	Parsed as a floating-point number; malformed/missing values are ignored
exit_code query parameter	Stored if present; does not determine status
POST body	JSON parsed when valid; otherwise retained as raw text

curl --fail --silent --show-error \
  --request POST --header 'Content-Type: application/json' \
  --data '{"processed":1200}' \
  "$PINGSTACK_PING_URL?value=42&exit_code=0"

PINGSTACK_PING_URL must be the privately stored location URL. HTTP 200 means the ingestion request was accepted. For an active check, it records activity, marks the location up and recalculates health. For a paused check, it returns 200 without recording activity.

Malformed numeric input does not reject a heartbeat and does not clear the previous value. Numeric threshold health can therefore remain based on an earlier reported value. JSON/raw payloads are diagnostic data, not arbitrary status-setting instructions.

Ingestion is rate limited to 60 requests within a minute under the endpoint’s request limiter; excess requests return 429. This is separate from the automation grant/account limits. It is not a high-volume metrics ingestion API.

Do not send exit_code=1 expecting failure status. Report only the completion signal you intend to monitor; see recipes.