The account behind this key: its plan, the days this key may read (meta.history_floor and history_ceiling, null when open), the categories this key may read, the paired devices and when each last synced, the account time zone, and when this share expires (expires_at: past it, every call fails until the person renews the share in the app). Call this first.
Parametersclient
Every metric there is a figure for, with its unit and the first and last day. Use the exact metric names from here in query_metrics.
Parametersclient
query_metrics
Query metrics
Each day's figures as the Metrics Nest app shows them, or weekly or monthly buckets. One row per metric and day (one per reading for metrics read reading by reading), already combined: food and water include what was logged in the app and what other apps wrote to Health, so never add rows together. Paged: follow next_cursor while it is set; meta.truncated names the days a page covers when there are more. A window outside what the share allows is narrowed to it (meta.history_floor and history_ceiling).
Parameterstofromlimitclientcursormetricgranularity
query_intraday
Query hourly readings
Hour-by-hour readings such as heart rate, kept 90 days. One row per metric, hour and device. Needs the intraday category.
Parametersdatelimitclientcursordevicemetric
One row per night, keyed by the morning it ended on: bed and wake times, and seconds asleep and in each stage. With several devices, the longest sleep is the night. get_night has the stages.
Parameterstofromlimitclientcursor
One night in full, including the stage-by-stage hypnogram.
Parametersclientwake_daterequired
list_workouts
List workouts
Workouts with activity, start and end, duration, distance, energy, the heart rate summary and the note. Sets and the route are on get_workout.
Parameterstofromlimitclientcursoractivity
One workout in full: the heart rate trace (average bpm and how many readings, minute by minute from the start) and zones, and the exercises and sets and the route when they were shared.
Parametersidrequiredclient
query_logs
Query food, drink and weight logs
What the person logged in the app: food with calories, macros and fruit and veg portions, drinks by kind (coffee, water, alcohol...), and typed weight. Each entry carries its time and part of day: morning, midday, evening or late. For a day's totals, use query_metrics.
Parameterstofromkindlimitclientcursorpart_of_day
list_exercises
List exercises
Every exercise logged in a workout (bench press, squat...), most recently done first, with how many workouts it was in, the first and last day, the heaviest weight lifted in kg (best_weight_kg), and the muscles it trains (null where the person never said, for an exercise of their own). Use an id or name from here in exercise_history. Needs the sets category.
Parametersclient
exercise_history
Exercise history
How one exercise has gone over time, as the app's exercise screen shows it: every workout it was in, newest first, with the sets (weight kg, reps, RPE, time s, distance m, and reps_left — how many more reps the set had in it, which is how the app asks effort), the best set (the heaviest, then most reps) and its weight in kg (top_weight_kg), volume, mean RPE, hard sets (within three reps of failure) and whether it was a PR (heavier, or the same weight for more reps). Nothing is estimated. For "how is my bench press improving", read top_weight_kg and best_set over time. Needs the sets category.
Parameterstofromclientexerciserequired
muscle_sets
Hard sets per muscle
Which muscles the training landed on over a window (default the last 7 days): hard sets per muscle — sets within three reps of failure, or unrated — read against the 10–20 per week most hypertrophy guidance uses, which muscles are still recovering (two or more hard sets in the last 48 hours), and exercises whose sets were not counted because the person never said what they train. For "what have I been training" or "what should I train next". Needs the sets category.
Parameterstofromclient
For a coach: the people who approved you as their coach, with what each lets you read and from when. Pass a client id as `client` to any other tool to read that person. A client who stopped sharing shows as ended.
Takes no parameters.
The goals set in the app: daily or weekly targets on a metric (a calorie ceiling, a water or step target) and journeys toward a value (a weight to reach), each with its progress as the phone last computed it. Needs the goals category.
Parametersclient
One goal's progress day by day, newest first: the figure, the fraction of the way there and whether it was met, as the phone computed it on each sync. Use it for how a goal has gone, not only where it stands. The id is from list_goals.
Parametersidrequiredtofromclient
The badges earned in the app, with tier and the time each was earned. Needs the goals category.
Parametersclient
propose_workout
Suggest a workout
Suggest a workout for the person to approve in the Metrics Nest app. This only leaves a suggestion: nothing is planned until they approve it on their phone, where they can also edit or reject it, and no workout is ever created, changed or deleted here. Call list_exercises first and give each exercise its exercise_id from there whenever it is one they have done; for one they have not, take its exercise_id from list_exercise_catalog when the app has it, and otherwise leave exercise_id out and give the name. Weights are kg. Make up a new idempotency_key for each suggestion and send the same one only when retrying this exact call: a retry answers the suggestion already made instead of making a second. Works only where the person allowed this connection to suggest workouts (get_profile says can_propose). list_proposals shows what became of each suggestion.
Parameterstitlerequiredclientactivityexercisesrequiredrationaleplanned_forrequiredidempotency_keyrequired
list_exercise_catalog
List the exercise catalog
Every exercise the Metrics Nest app offers, with the exercise_id propose_workout takes for it, its name and other names, its group, and the muscles it trains. The same for everybody; list_exercises is what this person has actually done.
Takes no parameters.
list_saved_workouts
List saved workouts
The workouts the person saved in the Metrics Nest app to start whenever they like ("Leg day", "Push A"), each with its id, exercises, sets and reps. propose_removing_saved_workout takes the id; propose_saved_workout adds a new one.
Parametersclient
propose_saved_workout
Suggest a saved workout
Suggest a named workout for the person to keep and start whenever they like ("Leg day"), rather than a session on one day (that is propose_workout). Nothing is saved until they approve it in the Metrics Nest app, where they can edit it first. Same exercises as propose_workout: exercise_id from list_exercises or list_exercise_catalog where there is one. Make up a new idempotency_key for each suggestion. Works only where the person allowed this connection to suggest (get_profile says can_propose).
Parameterstitlerequiredclientactivityexercisesrequiredrationaleidempotency_keyrequired
propose_removing_saved_workout
Suggest removing a saved workout
Suggest taking one of the person's saved workouts away. Nothing is removed until they approve it in the Metrics Nest app; the workouts already done from it stay. The id is from list_saved_workouts.
Parametersclientrationaleidempotency_keyrequiredsaved_workout_idrequired
list_proposals
List suggested workouts
The workouts suggested through this connection, newest first, and what became of each: pending, approved, rejected, or expired (unanswered for a week, or past its day). action says which kind each was: plan (a session on a day), save (a named workout to keep) or remove (a saved one taken away). For an approved one, approved_exercises is what the person approved and edited says whether they changed it; workout_ids are the workouts it was run as, and get_workout has what was actually done.
Parameterslimitclientstatus
withdraw_proposal
Withdraw a suggested workout
Take back a workout this connection suggested that the person has not answered yet: it leaves their list in the app. One they approved, rejected or that expired stays as it is. The id is from propose_workout or list_proposals.
Parametersidrequiredclient
propose_meal
Suggest a meal
Suggest a meal for the person to approve in the Metrics Nest app. This only leaves a suggestion: nothing is logged until they approve it and then log it from their phone, where they can change it on the plate first; no log entry is ever created, changed or deleted here. Give each food a name and, where you can, its grams and its calories and macros for that portion; leave out any figure you do not know rather than guessing. Make up a new idempotency_key for each suggestion and send the same one only when retrying this exact call. Works only where the person allowed this connection to suggest (get_profile says can_propose). list_meal_proposals shows what became of each suggestion.
Parametersslotitemsrequiredtitlerequiredclientrationaleplanned_forrequiredidempotency_keyrequired
list_meal_proposals
List suggested meals
The meals suggested through this connection, newest first, and what became of each: pending, approved, rejected, or expired (unanswered for a week, or past its day). log_ids are the food entries it was eaten as — query_logs has them, with meal_id set to the suggestion's id, and they say what was actually eaten, which may differ from what was suggested.
Parameterslimitclientstatus
withdraw_meal_proposal
Withdraw a suggested meal
Take back a meal this connection suggested that the person has not answered yet: it leaves their list in the app. One they approved, rejected or that expired stays as it is. The id is from propose_meal or list_meal_proposals.
Parametersidrequiredclient