---
title: "White-box KV round-trip probe"
method: GET
path: "/api/health/kv"
tags: ["health"]
---

# White-box KV round-trip probe

`GET /api/health/kv`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/health/kv`
- Auth: none required

Public, no auth. Times a SET+GET from INSIDE a serverless function, so it measures the exact path renders and crons use - a probe run next to the KV host could not see the degradation this exists to catch. Abuse-safe: one fixed key with a short TTL, so hammering it overwrites one key rather than amplifying writes. It answers 200 WITH THE MEASUREMENT whenever KV responds at all and puts the verdict in `degraded`; 503 means KV threw.

## Response `200`

The measurement. Read `degraded`, not the status code.

- HealthProbeResponse: Shared shape for the KV and blob probes — the blob probe reports its round trip under `kv_ms` too, so one canary parses both identically.
  - `ok` boolean, required
  - `kv_ms` integer, required: Measured round-trip milliseconds.
  - `degraded` boolean, required: THE VERDICT. A slow-but-alive dependency is a 200 with this set, not an outage.
  - `threshold_ms` integer
  - `backend` string: The live host the probe actually reached, read from the runtime config rather than hardcoded.
  - `at` string, date-time

## Other responses

- `503`: KV threw - not merely slow.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)