Hourly (circadian) trends
get_hourly_trendsAggregate glucose readings by clock-hour, showing average BG, time-in-range, and low/high counts per hour to identify recurring circadian patterns like dawn phenomenon and evening highs.
Instructions
Time In Range and average glucose pooled by clock-hour across the whole window, so every reading that fell in the 07:00 hour on any day is combined into one 07:00 row, and so on for all 24 hours.
Use it for "why am I always high/low at a certain time" questions, recurring circadian patterns, the dawn phenomenon and evening highs.
Hours are the device's own wall-clock hour (not UTC) — this already IS the patient's local hour at the time each reading was taken, so present it as-is with no conversion.
Returns: a byHour array of up to 24 rows, each with hour (wall clock, "HH:00"), averageBG, timeInRange, timeLow, timeHigh and the reading count for that hour. Glucose values are in the configured unit.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Required. Window end as an ISO 8601 timestamp, e.g. 2026-06-20T00:00:00.000Z — plain wall clock time, same caveat as start (the "Z" is a format artifact, not a UTC claim). Treated as inclusive and must be after start. All timestamps returned by this API are likewise plain wall clock time, unconverted. | |
| lower | No | Optional. Low (hypo) boundary in the chosen unit; readings below it count as time-low. Omit to use the server default (OMNI_LOWER). Pass only to override for this one call, e.g. to ask about time under a different threshold. | |
| start | Yes | Required. Window start as an ISO 8601 timestamp, e.g. 2026-06-19T00:00:00.000Z. IMPORTANT: despite the trailing "Z", this is plain WALL CLOCK time, not true UTC — Glooko records only the literal date/time the patient's device showed, with no timezone attached. Use the patient's own wall-clock digits directly (no conversion): resolve "yesterday" or "last 3 weeks" straight into the matching wall-clock date and time. Treated as inclusive. | |
| units | No | Optional. Glucose unit for this call. Omit to use the unit configured on the server (OMNI_UNITS). One of: "mmol" (mmol/L) or "mgdl" (mg/dL). Pass only to override the configured unit for this one call. | |
| upper | No | Optional. High (hyper) boundary in the chosen unit; readings above it count as time-high. Omit to use the server default (OMNI_UPPER). Pass only to override for this one call. |