Docs navigation

Search

Search, filter, and paginate exercises

`GET /v1/exercises` supports search queries, exact filters, random ordering, and standard offset-based pagination.

Supported filters

q
Full-text search query.
string
category
Top-level training category.
enum
muscle
Display muscle group or anatomical muscle name.
string
equipment
Equipment filter.
string
level
Difficulty level.
enum
force
Movement force classification.
enum
mechanic
Movement mechanic.
enum
random
Return random results instead of the default order.
boolean · default false
limit
Requested page size before plan-based clamping.
integer · default 20
offset
Zero-based offset into the result set.
integer · default 0

Search semantics

  • `GET /v1/exercises` returns `total: null` when `q` is present. Filter-only requests return a numeric total.
  • `limit` is validated up to 100 and then clamped to your plan's per-request result cap.
  • Free-tier pagination depth is capped at `offset + limit <= 500`.
  • `muscle` accepts either a display group such as `chest` or an anatomical name such as `latissimus dorsi`.

Categories

  • Strength · strength
  • Yoga · yoga
  • Mobility · mobility
  • Physical Therapy · physical_therapy
  • Stretching · stretching
  • Pilates · pilates
  • Calisthenics · calisthenics
  • Plyometrics · plyometrics
  • Conditioning · conditioning
  • Olympic Weightlifting · olympic_weightlifting
  • Powerlifting · powerlifting
  • Strongman · strongman
Search response (`total: null`)
{
  "data": [
    {
      "id": "barbell-bench-press",
      "name": "Barbell Bench Press",
      "keywords": [
        "bench",
        "press",
        "chest",
        "barbell",
        "pecs"
      ],
      "primaryMuscles": [
        "chest"
      ],
      "secondaryMuscles": [
        "front delts",
        "triceps"
      ],
      "equipment": "barbell",
      "force": "push",
      "level": "intermediate",
      "mechanic": "compound",
      "category": "strength",
      "instructions": [
        "Lie on a flat bench with your feet planted.",
        "Unrack the bar and lower it to mid-chest with control.",
        "Press the bar back to lockout while keeping your upper back tight."
      ],
      "exerciseTips": [
        "Keep your shoulder blades retracted.",
        "Drive your feet into the floor throughout the rep."
      ],
      "commonMistakes": [
        "Bouncing the bar off the chest.",
        "Letting the elbows flare aggressively at the bottom."
      ],
      "safetyInfo": "Use a spotter or safety pins when working near failure.",
      "overview": "A compound upper-body press that trains the chest, shoulders, and triceps.",
      "variations": [
        "Close-Grip Bench Press",
        "Paused Bench Press"
      ],
      "images": []
    }
  ],
  "total": null,
  "limit": 10,
  "offset": 0
}
Filter-only response (`total` numeric)
{
  "data": [
    {
      "id": "barbell-bench-press",
      "name": "Barbell Bench Press",
      "keywords": [
        "bench",
        "press",
        "chest",
        "barbell",
        "pecs"
      ],
      "primaryMuscles": [
        "chest"
      ],
      "secondaryMuscles": [
        "front delts",
        "triceps"
      ],
      "equipment": "barbell",
      "force": "push",
      "level": "intermediate",
      "mechanic": "compound",
      "category": "strength",
      "instructions": [
        "Lie on a flat bench with your feet planted.",
        "Unrack the bar and lower it to mid-chest with control.",
        "Press the bar back to lockout while keeping your upper back tight."
      ],
      "exerciseTips": [
        "Keep your shoulder blades retracted.",
        "Drive your feet into the floor throughout the rep."
      ],
      "commonMistakes": [
        "Bouncing the bar off the chest.",
        "Letting the elbows flare aggressively at the bottom."
      ],
      "safetyInfo": "Use a spotter or safety pins when working near failure.",
      "overview": "A compound upper-body press that trains the chest, shoulders, and triceps.",
      "variations": [
        "Close-Grip Bench Press",
        "Paused Bench Press"
      ],
      "images": []
    }
  ],
  "total": 2198,
  "limit": 20,
  "offset": 0
}