Types

ActivityDay

Heatmap cell.

Field	Type	Description
date	Date!	Date.
minutes	Int!	Minutes trained.
volume	Float!	Load lifted, kg × reps (warm-ups left out).

Admin

Admin dashboard. Every field requires the admin role.

Field	Type	Description
inviteOnly	Boolean!	Invite-only sign-up is on.
invites	[Invite!]!	Invite codes.
signIns	[SignIn!]!	Recent sign-ins, newest first (kept 90 days).
trainingNow	[TrainingNow!]!	Who is mid-workout right now.
user	AdminUserDetail	Drill into one user.
users	[AdminUser!]!	All users with workout counts and last activity.

AdminUser

A user as seen by an admin.

Field	Type	Description
createdAt	Timestamp!	Sign-up time.
disabled	Boolean!	Disabled: signed out and locked out everywhere.
email	String!	Email.
id	ID!	User id.
isAdmin	Boolean!	Admin.
isGuest	Boolean!	Guest account.
lastActive	Timestamp	Last workout start.
name	String!	Name.
workouts	Int!	Workouts logged.

AdminUserDetail

One user’s history. Reading it is recorded in the audit log.

Field	Type	Description
bodyweight	[BodyweightEntry!]!	Body-weight log.
id	ID!	User id.
workouts	[Workout!]!	All workouts, newest first.

ApiKey

A personal API key for calling the GraphQL API from scripts and tools (“Authorization: Bearer gg_…”). Only its first characters are kept in clear.

Field	Type	Description
access	ApiKeyAccess!	Read only, or read and write.
createdAt	Timestamp!	Created.
expiresAt	Timestamp	When it stops working; null when it never expires.
id	ID!	Key id (not the key itself).
lastUsedAt	Timestamp	Last request made with it.
name	String!	Name given when it was created.
start	String	First characters, to recognise it.

ApiKeyAccess

What a personal API key may do with its owner’s data.

Value	Description
read	Queries only; every mutation is refused.
write	Queries and mutations.

AppConfig

Public instance configuration the client needs before sign-in.

Field	Type	Description
catalogVersion	String!	Exercise library version.
defaultLocale	String	Language for visitors whose browser asks for none of the supported ones; null means English.
guestAccess	Boolean!	Guest accounts (and new passkey-only accounts, which start as guests) can be created.
instructionLocales	[String!]!	Languages with exercise instructions; others fall back to English.
inviteOnly	Boolean!	An invite code is required to create an account.
mediaAttribution	String!	Required credit line for exercise media.
mediaBaseUrl	String	Base URL for licensed exercise media; null hides animations.
passwordSignUp	Boolean!	New accounts can be created with an email and password. Otherwise a password is added in Settings to an account that signed in another way.
photoUploads	Boolean!	Custom exercises can have a photo (setCustomExercisePhoto); off when no storage is bound.
providers	[String!]!	Enabled sign-in methods besides passkeys: OAuth providers (google, github, cloudflare) and email (password sign-in: always in local development, elsewhere when the instance turns it on).
vapidPublicKey	String	Web Push application server key; null when push is not configured.

BalanceLift

One lift in the comparison.

Field	Type	Description
exerciseId	ID!	Exercise.
oneRm	Float!	Best estimated 1RM, kg.
ratio	Float!	Reference share of a back squat.
share	Float!	Where it stands against the others: 1 = in line with the strongest, lower = behind.

BodyFigure

Figure drawn by the muscle map.

Value	Description
female	Female figure
male	Male figure

BodyweightEntry

One body-weight reading per day, kg.

Field	Type	Description
date	Date!	Date.
weight	Float!	Weight, kg.

ConnectedApp

An app the user allowed to use their account through OAuth, such as an AI assistant connected to the remote MCP server.

Field	Type	Description
clientId	ID!	OAuth client id.
connectedAt	Timestamp	When the user allowed it.
icon	String	Logo URL the app registered.
name	String	Name the app registered.
uri	String	Home page the app registered.

CreatedApiKey

A new API key. The full key is returned only here, once.

Field	Type	Description
apiKey	ApiKey!	The key as it is listed.
key	String!	The full key (“gg_…”). Store it now: it cannot be shown again.

CustomExercise

An exercise the user created. Behaves like a library exercise everywhere.

Field	Type	Description
bodyPart	String!	Body part; cardio logs time + speed.
deleted	Boolean!	Deleted; kept so logged workouts can still show the name.
description	String	Setup and cues; searchable.
equipment	String	Equipment, if any.
id	ID!	Id, prefixed c_.
name	String!	Name.
photoUrl	String	Your photo of the exercise, readable only by you (same-origin, with your session). Null without one.

Date

Calendar date in the user’s own timezone, formatted YYYY-MM-DD.

Custom scalar.

EffortScale

Scale a single set’s effort was logged with. Each set keeps its own.

Value	Description
rir	Reps in reserve (0 = failure)
rpe	RPE, 1–10

EffortSetting

Which effort column a working set shows. Off by default.

Value	Description
none	No effort column
rir	Reps in reserve
rpe	Rate of perceived exertion

EffortStats

Effort over a period, always alongside how much was rated.

Field	Type	Description
averageRir	Float	Average RIR.
distribution	[Int!]!	Rated sets per RIR bucket 0,1,2,3,4,5+.
nearFailureShare	Float	Share of rated sets at RIR ≤ 1.
ratedSets	Int!	Sets with a rating.
totalSets	Int!	Working sets.
weeks	[EffortWeek!]!	Week by week.

EffortWeek

Weekly effort average.

Field	Type	Description
averageRir	Float!	Average RIR.
ratedSets	Int!	Rated sets.
totalSets	Int!	All working sets that week.
weekStart	Date!	Monday of the week.

EquipmentProfile

A place the user trains at and the equipment it has.

Field	Type	Description
equipment	[String!]!	Equipment keys.
id	ID!	Id.
name	String!	Name.

ExerciseSetting

Per-exercise settings. Weights in kg.

Field	Type	Description
addedLoad	Float	Added load for a bodyweight exercise.
bodyweight	Boolean	Overrides the library bodyweight flag.
exerciseId	ID!	Exercise id.
favourite	Boolean!	Starred by the user.
notes	String	Personal notes.
repCeiling	Int	Past this many reps, add a set instead.
step	Float	Load step; null uses the default.
unilateral	Boolean	Overrides the library per-side flag.
workingWeight	Float	Confirmed working weight.

ExerciseStats

Progress for one exercise.

Field	Type	Description
best	Float	Best top set ever.
bestOneRm	OneRmEstimate	Best estimate (≤ 12 reps).
exerciseId	ID!	Exercise.
points	[ProgressPoint!]!	Sessions, oldest first.

ExerciseTarget

What the next session asks of one routine item, and why.

Field	Type	Description
bodyweight	Boolean!	No load column.
exerciseId	ID!	Exercise.
itemId	ID!	Routine item.
mode	SetMode!	How it is logged.
perSide	Boolean!	Show reps per side.
reason	Reason!	Why these targets.
restSec	Int	Rest override.
rule	ProgressionRule!	Rule applied.
sets	[SetTarget!]!	Per-set targets.
supersetGroup	String	Superset group.

FinishResult

Outcome of finishing a workout.

Field	Type	Description
muscles	[MuscleSets!]!	What was just trained.
records	[PersonalRecord!]!	Records set.
workout	Workout!	The saved workout.

HevyPage

One page of workouts from Hevy, as Hevy returns them (read with readHevyApi in the SDK).

Field	Type	Description
page	Int!	This page, from 1.
pageCount	Int!	Pages in total.
workouts	JSON!	Hevy workout objects, newest first.

ImportPlanResult

What a plan import added.

Field	Type	Description
customExercises	Int!	Custom exercises created; others were matched by name.
dropped	[String!]!	Unknown exercise ids that were left out.
routines	Int!	Routines added (with fresh ids).
weekReplaced	Boolean!	The week schedule was taken over.

ImportResult

What an import wrote.

Field	Type	Description
bodyweight	Int!	Body-weight readings written.
customExercises	Int!	Custom exercises created.
sets	Int!	Sets written.
skippedDays	[String!]!	Dates that already had data and were left alone.
workouts	Int!	Workouts written.

Invite

An invite code for invite-only sign-up.

Field	Type	Description
code	String!	Code.
createdAt	Timestamp!	Created.
revokedAt	Timestamp	When it was revoked.
usedAt	Timestamp	When it was used.
usedBy	ID	User who used it.

JSON

Arbitrary JSON value.

Custom scalar.

LiftBalance

The main barbell lifts compared with each other through reference ratios to the back squat.

Field	Type	Description
lifts	[BalanceLift!]!	Lifts with an estimate.
weakest	ID	The lift furthest behind; null with fewer than two lifts.

MuscleBalance

Where training went in a period.

Field	Type	Description
muscles	[MuscleSets!]!	Worked muscles, most first.
untrained	[String!]!	Muscles that got nothing.

MuscleRecovery

How much recent training a muscle still carries, and how long since it was trained.

Field	Type	Description
daysSince	Int	Days since then.
fatigue	Float!	0 = fresh … 1 = carrying a lot of recent work.
lastTrained	Date	Last workout that trained it.
muscle	String!	Muscle key.
strength	Float!	1 = trained in the last two weeks, fading toward 0.15 over 90 days; 0 = never trained.

MuscleSets

Effective sets for one muscle (primary = 1, supporting = 0.5).

Field	Type	Description
muscle	String!	Muscle key.
sets	Float!	Effective sets.

OneRmEstimate

Estimated one-rep max, naming the set it came from.

Field	Type	Description
date	Date!	Source set date.
reps	Int!	Source set reps.
value	Float!	Estimate, kg.
weight	Float!	Source set weight.

PersonalRecord

A personal record set by a workout.

Field	Type	Description
exerciseId	ID!	Exercise.
kind	RecordKind!	Kind.
previous	Float!	Previous best.
value	Float!	New best.

PinnedNote

A note pinned to an exercise during a workout.

Field	Type	Description
date	Date!	Workout it was written in.
exerciseId	ID!	Exercise.
note	String!	The note.

PlanOverride

A one-off change to a single date, leaving the weekly plan alone.

Field	Type	Description
date	Date!	Date.
routineId	ID	Routine for that date; null = rest.

PlanShare

A link to a snapshot of the user’s plan.

Field	Type	Description
expiresAt	Timestamp!	Expiry.
token	String!	Share token, used in /share/.

ProgressionRule

Rule that picks the next session’s targets.

Value	Description
double	Double progression through a rep range
greyskull	Greyskull LP: AMRAP final set, double jumps, 10 % resets
linear	Add a step after every clean session; deload after three misses
none	Repeat last time
time	Add time to timed holds

ProgressPoint

One session on an exercise curve.

Field	Type	Description
date	Date!	Date.
effortRir	Float	Average RIR of rated sets.
oneRm	Float	Best estimated 1RM that session.
top	Float	Top set (kg), longest hold (s) or most reps.
topReps	Int	Reps of the top set.
volume	Float!	Weight × reps.

Reason

Translatable explanation of a target. Clients render code with params in the user’s language.

Field	Type	Description
code	String!	Message key, e.g. linear.up or deload.
params	JSON	Values interpolated into the message.

RecordKind

Kind of personal record.

Value	Description
duration	Longer hold
oneRm	Better estimated one-rep max
reps	More bodyweight reps
weight	Heavier load

Routine

A named session template.

Field	Type	Description
deload	Boolean!	Planned deload: opens on the plan and never feeds progression.
icon	String!	Icon key.
id	ID!	Id.
items	[RoutineItem!]!	Exercises in order.
name	String!	Name.
progression	ProgressionRule!	Default rule for its exercises.

RoutineItem

One exercise in a routine.

Field	Type	Description
bursts	Int!	Rest-pause bursts after the last work set.
drops	Int!	Drop sets after the last work set.
durationSec	Int	Target hold or cardio duration.
exerciseId	ID!	Library or custom exercise id.
id	ID!	Client key, stable within the routine.
mode	SetMode!	How it is logged.
progression	ProgressionRule	Overrides the routine rule.
reps	Int!	Target reps (range bottom for double progression).
repsMax	Int	Range top for double progression.
restSec	Int	Rest override, seconds.
sets	Int!	Number of sets.
supersetGroup	String	Items sharing a group are performed back-to-back.
warmups	Int!	Warm-up sets, ramped toward the first work weight.
weight	Float	Starting weight, kg.

SessionStart

Where a planned session takes its numbers from when progression does not decide.

Value	Description
last	The last session of that routine slot
plan	The routine’s own sets, reps and weight

SetKind

What a logged row is.

Value	Description
drop	Drop set right after the set before it; counts for volume, not progression
restpause	Rest-pause burst after a short pause; counts for volume, not progression
warmup	Warm-up: out of volume, records and progression
work	A working set

SetMode

How an exercise is logged.

Value	Description
cardio	Time + speed
reps	Weight × reps
time	Timed hold, optionally loaded

SetTarget

Target for one set. Weights in kg.

Field	Type	Description
amrap	Boolean!	As many reps as possible.
durationSec	Int	Hold or duration.
kind	SetKind!	Work, warm-up, drop set or rest-pause burst.
reps	Int	Reps.
speed	Float	Cardio speed.
weight	Float	Load.

Settings

Per-user preferences, synced across devices.

Field	Type	Description
accent	String!	Accent colour key.
activeProfile	ID	Profile the library and picker filter to; null shows everything.
bars	JSON	Bar weights in kg by bar type (barbell, ez, trap, smith); null: standard bars.
bodyFigure	BodyFigure!	Muscle map figure.
demoMinimized	Boolean!	Exercise animation minimised during workouts.
effortScale	EffortSetting!	Effort column for new sets.
equipmentProfiles	[EquipmentProfile!]!	Equipment profiles; bodyweight exercises are always available.
homeBodyweight	Boolean!	Show the body-weight card on Home.
keepAwake	Boolean!	Keep the screen awake while a workout runs.
locale	String!	UI language code.
plates	[Float!]	Plate weights owned, kg, each once (pairs assumed); null: the standard set.
reminderOn	Boolean!	Push a reminder on planned days without a workout.
reminderTime	String!	Reminder time, HH:MM local.
restSec	Int!	Default rest between sets, seconds.
restTimer	Boolean!	Start a rest timer after each set; an exercise with its own rest time always rests.
sessionStart	SessionStart!	Where planned sessions take their numbers from when progression does not decide.
sound	Boolean!	Beep when a timer ends.
targetWeight	Float	Body-weight goal in kg.
theme	Theme!	Colour theme.
timerFlash	Boolean!	Flash the screen when a timer ends.
timezone	String	IANA timezone detected by the browser.
unit	Unit!	Display unit.
weekStart	WeekStart!	First day of the week.
workoutLayout	WorkoutLayout!	Workout screen layout.

SharedPlan

A plan someone shared by link: routines, week and custom exercises only.

Field	Type	Description
expiresAt	Timestamp!	Link expiry.
ownerName	String	Display name of whoever shared it.
plan	JSON!	The plan file.

SignedInSession

A browser or CLI signed in to the account. The session token itself is never exposed.

Field	Type	Description
createdAt	Timestamp!	Signed in.
current	Boolean!	True for the session making this request.
expiresAt	Timestamp!	When it ends unless it is used again.
id	ID!	Session id (not the token).
ipAddress	String	Address it signed in from.
lastActiveAt	Timestamp!	Last time the session was refreshed.
userAgent	String	The browser or tool that signed in, as it named itself (the CLI sends “gymgym-cli/…”).

SignIn

A sign-in, as recorded for the admin dashboard (no IP address is kept).

Field	Type	Description
at	Timestamp!	When.
country	String	Country code from Cloudflare.
device	String	Browser and system, e.g. “Firefox · macOS”.
email	String!	Email.
isGuest	Boolean!	Guest account.
method	String!	How: google, github, passkey, password, guest, cli or another auth path.
name	String!	Name.
userId	ID!	User.

StarterKind

Ready-made plans.

Value	Description
fullBody	Two alternating full-body sessions (Greyskull LP)
ppl	Push / Pull / Legs, three days
upperLower	Upper / Lower, four days (double progression)

Theme

Colour theme.

Value	Description
dark	Dark
light	Light
system	Follow the OS

Timestamp

Milliseconds since the Unix epoch.

Custom scalar.

TodayPlan

The plan for one date.

Field	Type	Description
date	Date!	Date.
isOverride	Boolean!	The day was moved away from the weekly plan.
routine	Routine	The planned routine.
routineId	ID	Routine planned; null = rest.
workouts	[Workout!]!	Workouts already logged that date.

TrainingNow

Someone mid-workout right now.

Field	Type	Description
exerciseId	ID	Current exercise.
name	String!	Name.
setsDone	Int!	Sets done.
setsTotal	Int!	Sets planned.
updatedAt	Timestamp!	Last heartbeat.
userId	ID!	User.
workoutName	String!	Workout.

Unit

Weight unit used for display. Stored weights are always kilograms.

Value	Description
kg	Kilograms
lb	Pounds

Viewer

The signed-in user and all of their data. Only ever the caller’s own.

Field	Type	Description
activeWorkout	Workout	The running workout, readable from any device.
activity	[ActivityDay!]!	Minutes trained per day, for the heatmap.
apiKeys	[ApiKey!]!	Personal API keys for the GraphQL API, newest first.
backup	JSON!	Full backup of the user’s data as JSON.
bodyweight	[BodyweightEntry!]!	Body-weight readings, oldest first.
connectedApps	[ConnectedApp!]!	Apps (such as AI assistants on the remote MCP server) the user allowed to use the account.
customExercises	[CustomExercise!]!	Exercises the user created.
day	TodayPlan!	What is planned for a date.
effort	EffortStats!	Effort statistics over working sets.
email	String!	Email (only visible to the user themself).
exerciseSettings	[ExerciseSetting!]!	Per-exercise settings.
exerciseStats	ExerciseStats!	Progress curve, best estimated 1RM and best set for one exercise.
hevyWorkouts	HevyPage!	Read workouts from your Hevy account for importing (Hevy Pro: Settings → Developer → API key). The key is used for this request only and never stored. Nothing is written; import the result with ImportHistory.
id	ID!	User id.
image	String	Avatar URL.
isAdmin	Boolean!	Has the admin dashboard.
isAnonymous	Boolean!	Guest account that can still be linked to Google, GitHub or a passkey.
liftBalance	LiftBalance!	The main barbell lifts compared through reference ratios to the back squat.
muscleBalance	MuscleBalance!	Effective sets per muscle and the muscles that got nothing.
muscleRecovery	[MuscleRecovery!]!	Fatigue and time since last trained, per muscle, from the last 120 days.
name	String!	Display name.
nextTargets	[ExerciseTarget!]!	Targets for the next session of a routine, each with the reason behind it.
overrides	[PlanOverride!]!	One-off day changes.
pinnedNotes	[PinnedNote!]!	The newest pinned workout note of each exercise, shown in later workouts with it.
planFile	JSON!	The user’s plan as a shareable file: routines, week and the custom exercises they use. No workouts, weigh-ins or settings.
routine	Routine	One routine.
routines	[Routine!]!	Routines in display order.
sessions	[SignedInSession!]!	Browsers and CLIs signed in to the account, most recently active first. Needs a signed-in session.
settings	Settings!	Preferences.
streak	Int!	Weeks in a row with at least one workout.
week	[WeekDay!]!	The weekly plan, Monday to Sunday.
workout	Workout	One workout.
workouts	[Workout!]!	Finished workouts, newest first.

WeekDay

One weekday of the weekly plan.

Field	Type	Description
routineId	ID	Planned routine; null = rest.
weekday	Int!	Monday = 0 … Sunday = 6.

WeekStart

First day of the week in week views.

Value	Description
monday	Monday
sunday	Sunday

Workout

A training session, running (finishedAt = null) or finished.

Field	Type	Description
bodyweight	Float	Body weight entered at the start, kg.
date	Date!	Calendar date.
durationMin	Int!	Minutes trained.
exercises	[WorkoutExercise!]!	Exercises in order.
finishedAt	Timestamp	Finish time; null while running.
id	ID!	Client-generated id.
name	String!	Name.
notes	String	Notes about the session.
routineId	ID	Routine it came from.
skipProgression	Boolean!	The whole session is left out of progression.
startedAt	Timestamp!	Start time.

WorkoutExercise

One exercise block within a workout.

Field	Type	Description
exerciseId	ID!	Exercise id.
mode	SetMode!	How it was logged.
note	String	Today’s note on this exercise.
notePinned	Boolean!	Keep showing the note in later workouts with this exercise.
sets	[WorkoutSet!]!	Sets in order.
skipProgression	Boolean!	Left out of progression.
supersetGroup	String	Superset group.

WorkoutLayout

Workout screen layout.

Value	Description
cards	One exercise at a time
list	The whole session in one list

WorkoutSet

One logged set. Weights in kg.

Field	Type	Description
amrap	Boolean!	As many reps as possible (Greyskull final set).
done	Boolean!	Checked off.
durationSec	Int	Time actually held, or cardio duration.
effort	Float	Effort rating; null = unrated.
effortScale	EffortScale	Scale the rating was logged with.
kind	SetKind!	Work, warm-up, drop set or rest-pause burst.
reps	Int	Reps (total across both sides for per-side work).
repsLeft	Int	Left side reps, when logged per side.
repsRight	Int	Right side reps, when logged per side.
speed	Float	Cardio speed, km/h.
targetDurationSec	Int	Target hold.
targetReps	Int	Target reps.
targetWeight	Float	Target weight.
weight	Float	Load (added load for bodyweight).