telo

Create one structured workout requested by the user, scheduled within the next 7 days. Stores a pending plan; does NOT immediately deliver to or start Apple Watch. The first delivery is manual: open telo on iPhone > Planned workouts and tap Schedule on Watch to grant permission. Afterwards the user may opt into automatic delivery for newly created plans on that iPhone. Background scheduling is opportunistic, not immediate; otherwise review each plan manually. Use seconds/meters and an explicit local UTC offset. Step names can describe reps/weights; these are instructions, not native repetition goals. Pool swimming uses activity=swimming and location=indoor only. Optional pool_length_m is displayed for review; the user sets pool length on Watch when starting because WorkoutKit has no pool-length setter. pool_distance_with_time goals require meters and seconds, and advance only when BOTH distance and time are fulfilled (send-off intervals; overrunning distance delays the next step). Distance-only goals are also supported. Pool custom workouts require watchOS 11 or later. Device supportsActivity/supportsGoal validation can reject unsupported activities, goals or alerts before scheduling. Retry with the SAME idempotency_key and payload. Read workout_plans to check delivery and exact recorded results. Never claim the Watch received a pending plan.

Read the latest 50 planned workouts, or one by id, including the original prescription, delivery state and first exactly linked HealthKit workout. pending awaits iPhone processing (manual review, or automatic scheduling if enabled on that iPhone); scheduled means the iPhone scheduler accepted it, NOT confirmed Watch delivery; cancel_requested awaits iPhone removal. recorded_workout=null means no linked result has synced, not proof the workout was skipped. A linked recording does not prove every prescribed interval was completed. Use its uuid with workout_detail for analysis and ask for perceived effort. If truncated, query a known id. Plans have no automatic edits. Automatic scheduling is an optional iPhone setting after a first manual delivery; its current value and background execution time are unknown to the server.

Request cancellation of the user's identified workout plan. The iPhone must process removal, either during an automatic refresh or by opening telo > Planned workouts. Does not delete any recorded HealthKit result. Idempotent; cancel_requested is NOT confirmation of removal from Apple Watch. To change a prescription, cancel the old plan and create a new one for review.

Inspect before health reviews or investigating missing data. Returns the last received upload batch, collection date ranges/counts and per-metric coverage. Not a sync command. history_import is the iPhone's own report of its history import (complete, still arriving, or unknown for older app builds); when next_step is present, relay its message to the user; HealthKit read permissions are unknown. An upload can be empty or re-send old records; old dates alone do not prove stalled sync. No account identifiers returned.

Takes no parameters.

Lists the available health metrics, the unit of each one, and how far back the data goes. Call this before query_daily if you do not know the exact metric names.

Takes no parameters.

Daily records or week/month aggregates. aggregation identifies sum or unweighted average of stored daily values; daily_min/max are extrema of daily values, not raw samples. days_present counts stored dates; days_expected counts calendar dates in period_start/end clipped to the request, not expected sensor wear. Units and aggregation methods are kept separate. Entirely missing buckets/metrics have no row: missing is not zero. Weekly labels use SQLite %Y-W%W (Monday weeks split at New Year), not ISO weeks; use period_start/end. Limit 500 rows. If truncated, discard the partial response and re-query smaller non-overlapping ranges aligned to complete buckets, or fewer metrics. Do not combine partial bucket averages without weighting by days_present.

Detail for a workout UUID from sessions. Includes source/device, indoor flag, pool length, elevation gain, laps, classified segments, paired pause intervals, a swimming summary and reduced series when accessible in HealthKit. Summaries, events and zones are permanent; only raw series expire after 30 days. The iPhone must sync with a version that collects detail. raw_available and summary_available distinguish coverage. synced_at is the server ingestion time when recorded; older summaries fall back to the R2 object upload time (which may be the storage migration time). not_available means not synced. HR zones estimate active bucket time (excluding pauses) using one unambiguous HR source and six percent-max bands, including zone 0 below 50%. max_hr can override the observed personal workout maximum; observed maximum is an estimate, not a tested physiological maximum. Missing buckets are excluded and coverage is reported. Values[i] covers seconds [(offset+i)*interval_s, (offset+i+1)*interval_s) from workout start, clipped at elapsed_s; null is missing. Each series has its own source, do not sum or average duplicate metrics across sources. Averages are weighted by sample overlap; sums are prorated across buckets. Gaps and sampling limit precision, including time in HR zones. Events are normalized before pagination: pause/resume pairs become one pause with pause_kind and end_reason; unmatched resumes are marked, and trailing pauses end at workout end. Segment distance_basis distinguishes metadata from bucket estimates; distance_split labels are distance matches, not guaranteed native types. swimming_summary uses lap intervals minus the union of recorded pauses; gaps outside laps count as inferred rest. It preserves swimming_s, total_rest_s and pace_s_per_100m. wall_gaps exposes every consecutive unique lap transition (after_lap is 1-based, gap_s is next start minus previous end, manual_pause includes boundary/spanning pauses). sets contains HealthKit segments covering co

Sleep nights or workouts within an inclusive date range. Workout activity accepts run/bike/swim (or running/cycling/swimming). granularity=week groups workouts by Monday date and modality, summing duration, distance and estimated HR-zone seconds. Boundary weeks cover only the requested dates. Distance and zone coverage counts distinguish missing data from zero; max_hr uses the same definition as workout_detail. Filters and weekly grouping require kind=workout. Timestamps carry the local UTC offset.

Duration-based training workload (minutes), excluding walking unless include_walking=true: rolling ATL 7 days, CTL 42 days, same-day TSB=CTL-ATL and acute/chronic ratio. Not intensity-weighted TSS. Every training row includes trimp_load, trimp_atl, trimp_ctl and trimp_tsb: simple zone TRIMP = sum(zone_seconds[z] * z / 60), with weights [0,1,2,3,4,5] for zones 0–5. TRIMP ATL/CTL use 7/42-day rolling means; TSB=CTL-ATL. max_hr overrides the observed workout maximum. include_trimp=true also returns the legacy trimp object with coverage details. Existing duration fields remain unchanged. TRIMP sums observed zone time; workouts without usable zones contribute zero, so rolling ATL/CTL/TSB remain numeric with incomplete coverage. trimp_coverage, trimp_coverage_7d and trimp_coverage_42d report the fraction of included workout duration with usable HR zones for the day and rolling windows. Covered seconds are capped per workout at its duration; coverage is null when there is no included duration. Missing workout days count as zero; coverage is reported. HRV SDNN and resting HR compared with the preceding 30–60 calendar days, excluding the target date; at least 7 valid daily values required. Includes mean, population SD, absolute/percentage delta and z-score. Maximum 500 total rows; narrow the range if truncated.

Read the cards on the user's telo iPhone home screen, the dated marks they asked you to keep (e.g. 'Sick', 'Intervals start'), and recent changes. Marks are context the user gave about their life; use them when interpreting their data. Call before editing the home.

Takes no parameters.

Put a live chart on the user's telo iPhone home. Only when the user asks to pin, save, show or keep something on telo. The card keeps updating with each sync. Styles: trend (line), stat (number and change), bars. Optional: compare_with draws a second metric on the same window; baseline=personal draws the user's usual range; display=pace_km turns running_speed into min/km; goal only when the user stated one; color only when the user asks (cards default to a color per metric category); size=half puts two consecutive half cards side by side (a number and a small trend, details on tap); change_from=usual or year_ago changes what the change line compares with. Always pass the user's question in their words; it is shown on the card.

Add a countdown to a date the user named (a race, a trip, a test) to their telo home. telo counts days; it never judges them.

Change one card: title, window, style, comparison, usual range, color, size, change_from, or a goal the user stated. null removes an option. Call home first for ids.

Reorder cards, remove cards or remove marks, when the user asks to set up or tidy their home (e.g. 'set my home up for race week'). The reason is shown to the user in the change history, and every change can be undone on the phone.

Keep a short note the user told you about a date or span (illness, travel, new training, new shoes). It appears on every telo chart covering that date and is returned by home to any assistant later. Only for facts the user stated, never your inference.

Call when the user asked for something telo cannot do with the tools here: a chart or layout on the telo home, a metric telo does not have, data that is missing, a question no tool answers. Pass their request in their words, what you tried instead, and what is missing. Then tell the user you noted it for the telo team, without promising it will be built. Not for questions you can answer by reading their data.