---
title: "Advanced exercise filtering"
method: GET
path: "/api/v1/exercises"
tags: ["exercises"]
---

# Advanced exercise filtering

`GET /api/v1/exercises`

Filter exercises by multiple criteria with fuzzy search support and cursor-based pagination.

## Query parameters

- `name` string — Filter exercises by name. Supports fuzzy matching.
- `keywords` string — Filter exercises by keywords. Use comma-separated values for multiple keywords.
- `targetMuscles` string — Filter exercises by primary target muscles. Use comma-separated values for multiple muscles.
- `secondaryMuscles` string — Filter exercises by secondary muscles. Use comma-separated values for multiple muscles.
- `exerciseType` string — Filter exercises by type (e.g., strength, cardio).
- `bodyParts` string — Filter exercises by body parts. Use comma-separated values for multiple body parts.
- `equipments` string — Filter exercises by required equipment. Use comma-separated values for multiple equipment types.
- `limit` string — Maximum number of results to return (min: 1, max: 25, default: 10)
- `after` string — Exercise ID to paginate after (for forward pagination)
- `before` string — Exercise ID to paginate before (for backward pagination)

## Response `200`

Retrieve exercises by search filters

- object
  - `success` boolean, required — Indicates whether the request was successful
  - `meta` object, required — Metadata about cursor-based pagination
    - `total` number, required — Total number of exercises matching the filters
    - `hasNextPage` boolean, required — Whether there are more results after the current page
    - `hasPreviousPage` boolean, required — Whether there are results before the current page
    - `nextCursor` string — Cursor for the next page (exercise ID)
    - `previousCursor` string — Cursor for the previous page (exercise ID)
  - `data` object[], required — Array of exercises matching the filter criteria
    - `exerciseId` string, required — The id of the exercise
    - `name` string, required — The name of the exercise.
    - `equipments` string[], required — List of equipment required for the exercise.
    - `bodyParts` string[], required — Primary body parts targeted by the exercise.
    - `exerciseType` string, required — Type of exercise (e.g., cardio,strength).
    - `targetMuscles` string[], required — Primary muscles targeted by the exercise.
    - `secondaryMuscles` string[], required — Secondary muscles engaged during the exercise.
    - `imageUrl` string — URL of the exercise image
    - `keywords` string[], required — Keywords associated with the exercise for searchability.

## Other responses

- `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
- `401` — Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
- `403` — The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
- `404` — The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.
- `405` — The request method is not supported by the target resource. The server must generate an Allow header field in a 405 response containing a list of the target resource's currently supported methods.
- `409` — This response is sent when a request conflicts with the current state of the server.
- `412` — The requested operation cannot be completed because certain conditions were not met. This typically occurs when a required resource state or version check fails.
- `429` — The user has sent too many requests in a given amount of time ("rate limiting")
- `500` — The server has encountered a situation it does not know how to handle.

---

[API](https://skmtc.dev/ascendapi/apis/exercisedb-v1.md) · [All operations](https://skmtc.dev/ascendapi/apis/exercisedb-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ascendapi/exercisedb-v1/revisions/c5d4e79509c5/schema)