Loki Docs
Tools › Exercises › Find exercises

Find exercises

find_exercisesReads
What it does
Reads only. Changes nothing.
Permission
Exercises, read exercises:read

What your assistant is told

Search the exercise catalog. Returns lightweight summaries matching the optional case-insensitive fragment of a name OR an alias ("DB bench", "pec deck" — search never runs on slugs), narrowed by equipment and by muscle. Includes the user's own custom exercises. A catalog exercise carries a stable slug (e.g. "barbell-back-squat"); a custom one has no slug and is addressed by its numeric id, which every catalog row also answers to — so pass id when slug is null. Each result carries its primaryMuscle (one of the 17 display groups) and equipment — so "which muscles does this train?" needs no follow-up call per hit; get_exercise is for the instructions. **"What can I do here?" is onlyWhatIOwn: true** (with an optional place). That returns only exercises the user can ACTUALLY do: every piece of equipment an exercise requires has to be something they have, so a dumbbell bench press needs the bench too. Use it before programming anything. equipment / anyEquipment are the weaker question — exercises that USE this kit, whether or not the user has the rest of what they need. Pass real equipment slugs from list_equipment, get_my_equipment or a result's equipment (dumbbell, flat-bench, 45-degree-leg-press), or body-only for "needs no equipment at all". A general type matches its kinds and a specific kind matches its type: leg-press finds both leg presses, and an adjustable-bench also does the flat-bench lifts (never the reverse). muscles matches any of the primary muscles given — a display group ("chest") or one of the anatomical muscles a get_exercise result names ("pectoralis-major-clavicular"). The catalog's own vocabularies narrow it too: pattern is the MOVEMENT and says nothing about how it loads (a pull-up, a lat pulldown and an assisted pull-up are all "vertical-pull"); bodyRegion is "upper" | "lower" | "core" | "full-body"; level is "beginner" | "intermediate" | "advanced". **tags are safety claims and they AND**, unlike every other filter here: pass them when the user tells you something hurts, and read each tag's definition off a get_exercise result before you pick one. To find "something else for this lift" use suggest_substitution instead — it already knows the pattern and the region to hold. Only exercises still in the catalog are returned — retired ones are left out, so anything you find here is safe to program. A slug from the user's own history may nonetheless be a retired exercise; get_exercise still resolves it and names its replacement.

Parameters

  • querytext, optionalCase-insensitive name fragment. Omit to list the first limit exercises.
  • equipmenttext, optionalFilter to exercises that use this equipment slug, e.g. "barbell" or "flat-bench". Omit for any. Prefer anyEquipment for more than one.
  • limitwhole number, optionalMaximum number of results (default 25, capped at 100).
  • anyEquipmentlist of text, optionalFilter to exercises using ANY of these equipment slugs, e.g. ["dumbbell", "body-only"]. Combines with equipment (both must hold).
  • muscleslist of text, optionalFilter to exercises whose PRIMARY muscle is any of these slugs, e.g. ["chest", "triceps"]. From a result's primaryMuscle, or /v1/muscles.
  • onlyWhatIOwntrue or false, optionalTrue = only exercises the user can do with what they actually have (EVERY requirement met). Needs get_my_equipment to have something in it; with nothing recorded it answers bodyweight exercises only.
  • placetext, optionalWhich place onlyWhatIOwn means: a place's name (case-insensitive), or "home" / "gym". Omit for everything they own anywhere. Ignored without onlyWhatIOwn.
  • patternslist of text, optionalFilter to exercises whose MOVEMENT PATTERN is any of these, e.g. ["vertical-pull"] or ["squat", "lunge"]. The pattern of any exercise is on its get_exercise result. The pattern is the movement, never the loading.
  • bodyRegionslist of text, optionalFilter to exercises in any of these body regions: "upper", "lower", "core", "full-body".
  • tagslist of text, optionalSafety tags EVERY result must honour — "knee-safe", "lower-back-safe", "shoulder-safe", "no-axial-load", "high-impact". The first four are claims of safety: asking for one keeps only the exercises that carry it. "high-impact" is the one that names a HAZARD (jumps, landings, the barbell Olympic lifts), so asking for it means "no jumping" and EXCLUDES those rows. Each tag's exact claim is on a get_exercise result; use them when something hurts, and never guess a tag's meaning from its name. Excludes the user's own exercises, which carry no reviewed claims.
  • levelslist of text, optionalFilter to exercises at any of these levels: "beginner", "intermediate", "advanced". Excludes the user's own exercises, which the catalog does not rate.