Bucketed trend over any timeframe
get_trendCompare glucose, insulin, and carb metrics across time buckets to identify trends and assess data reliability.
Instructions
Glucose, insulin and carb aggregates split into time buckets across a span, for "how have things changed month by month over the last year" style questions.
Each bucket is computed independently from the raw readings (not by averaging averages), so a year split by month returns 12 correct rows in a single call without pulling raw data back to you. Prefer this over making many separate summary calls for a multi-period comparison.
Insulin per bucket follows the same rule as elsewhere: bolus is summed from individual events; basal comes from Glooko's per-day totals. Each bucket also reports observedDays (the real decimal span of data in it) and a coverage percentage, so you can judge which rows to trust.
Returns: bucketCount and a buckets array. Each row has: bucket (period key), start, end, observedDays; glucose (avg, timeInRange, timeLow, timeHigh, stdDev, coefficientOfVariation, gmiEstimatedA1c, cgmReadingCount); insulin (bolusUnits, bolusUnitsPerDay, bolusEventCount, avgUnitsPerBolus, and when Glooko daily data exists basalUnits, basalDayCount, averageBasalUnitsPerDay, basalPercent, bolusPercent); carbs (carbsGrams, carbsPerDay, carbEntryCount); and coverage (cgmReadingCount, expectedReadingCount, coveragePercent, trustworthy).
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. | |
| mode | No | Optional (default: "calendar"). How the span is divided into buckets. "calendar" uses real calendar units (days/weeks/months/quarters) with ragged edges at the ends; "fixed" uses equal-length buckets of fixedSizeDays counting from the start date. Choose the bucket size with "granularity" (calendar) or "fixedSizeDays" (fixed). | calendar |
| 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. | |
| granularity | No | Optional (default: "month"). Calendar bucket size. Only used when mode is "calendar". One of: "day", "week", "month", "quarter". | month |
| fixedSizeDays | No | Optional (default: 7). Length of each bucket in days. Only used when mode is "fixed". |