Histories API Documentation
This document describes the Histories API, which returns the recorded results of completed training and testing sessions for all players in your organization.
Table of Contents
- Overview
- Authentication
- REST API Endpoint
- Response Fields
- Categories and Data Fields
- Parameter Validation
- Error Handling
- Examples
Overview
A history is the result of one completed session (one protocol workout) by one player. It contains the metrics calculated from that session, such as peak and average forces, rate of force development values, and test scores.
- One request returns the histories of every player in the organization that owns the API key.
- Each history covers a whole session, not a single rep. Raw per-rep force readings are not exposed.
- The
categoryof a history identifies the protocol it belongs to and determines which fields appear in itsdataobject.
Authentication
All API endpoints require authentication. Include a valid api-key in the headers:
api-key: <your_api_key>
If the key is missing or invalid, the API responds with 401 Unauthorized.
REST API Endpoint
List Histories for an Organization
Returns all histories created within the given date range for every player in your organization.
GET /api/histories
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
start_date |
string | No | Exactly 7 days before now | Start date in ISO 8601 format (YYYY-MM-DD). Inclusive: starts at 00:00:00 UTC on this date. |
end_date |
string | No | Now | End date in ISO 8601 format (YYYY-MM-DD). Inclusive: ends at 23:59:59 UTC on this date. |
Histories are filtered by the time they were created (the date field).
The response is not paginated. All histories in the range are returned in a single response.
Response
The response body is a JSON array of histories in no guaranteed order. An empty range returns [].
[
{
"id": 48211,
"date": "2026-11-03T14:22:05Z",
"category": "rapid_strength_test",
"session_hand": "right",
"player": {
"id": 1093,
"email": "player1@example.com",
"first_name": "Jane",
"last_name": "Doe",
"mlb_id": "123456"
},
"data": {
"four_finger_finger_tip_flexion_peak": 61.4,
"four_finger_finger_tip_extension_peak": 18.9,
"four_finger_mid_finger_flexion_peak": 55.2,
"ulnar_deviation_peak": 72.0,
"radial_deviation_peak": null
}
}
]
Response Fields
| Field | Type | Description |
|---|---|---|
id |
integer | Unique history ID. |
date |
string | UTC timestamp (ISO 8601, e.g. 2026-11-03T14:22:05Z) when the history was created. |
category |
string | The protocol the history belongs to. See Categories and Data Fields. |
session_hand |
string | null | Hand used for the session: "left", "right", or null if not recorded. |
player.id |
integer | FlexPro Grip user ID. Same value as the user_id returned by the Account Integration API. |
player.email |
string | Player email address. |
player.first_name |
string | null | Player first name. |
player.last_name |
string | null | Player last name. |
player.mlb_id |
string | null | Player MLB ID, if set. |
data |
object | Session metrics. Shape depends on category. |
Categories and Data Fields
Every data value is a number or null, except variant and protocol_name in Scored Tests, which are strings.
Strength Tests
| Category | Data fields |
|---|---|
strength_test |
four_finger_finger_tip_flexion_peakindex_finger_finger_tip_flexion_peakmiddle_finger_finger_tip_flexion_peakring_finger_finger_tip_flexion_peaklittle_finger_finger_tip_flexion_peakfour_finger_extension_peakindex_finger_extension_peakmiddle_finger_extension_peakring_finger_extension_peaklittle_finger_extension_peakfour_finger_mid_finger_flexion_peakindex_finger_mid_finger_flexion_peakmiddle_finger_mid_finger_flexion_peakring_finger_mid_finger_flexion_peaklittle_finger_mid_finger_flexion_peakulnar_deviation_peakradial_deviation_peak |
rehab_strength_test |
Same fields as strength_test. |
rapid_strength_test |
four_finger_finger_tip_flexion_peakfour_finger_finger_tip_extension_peakfour_finger_mid_finger_flexion_peakulnar_deviation_peakradial_deviation_peak |
Strength Training (A / B / C Days)
| Category | Data fields |
|---|---|
training_a_day |
four_finger_finger_tip_flexion_peakfour_finger_finger_tip_flexion_average_rep_two_to_fiveindex_finger_finger_tip_flexion_peakindex_finger_finger_tip_flexion_average_rep_two_to_fivemiddle_finger_finger_tip_flexion_peakmiddle_finger_finger_tip_flexion_average_rep_two_to_fivering_finger_finger_tip_flexion_peakring_finger_finger_tip_flexion_average_rep_two_to_fivelittle_finger_finger_tip_flexion_peaklittle_finger_finger_tip_flexion_average_rep_two_to_fiveulnar_deviation_peakulnar_deviation_average_rep_two_to_five |
training_b_day |
four_finger_extension_peakfour_finger_extension_average_rep_two_to_fiveindex_finger_extension_peakindex_finger_extension_average_rep_two_to_fivemiddle_finger_extension_peakmiddle_finger_extension_average_rep_two_to_fivering_finger_extension_peakring_finger_extension_average_rep_two_to_fivelittle_finger_extension_peaklittle_finger_extension_average_rep_two_to_fiveradial_deviation_peakradial_deviation_average_rep_two_to_five |
training_c_day |
four_finger_mid_finger_flexion_peakfour_finger_mid_finger_flexion_average_rep_two_to_fiveindex_finger_mid_finger_flexion_peakindex_finger_mid_finger_flexion_average_rep_two_to_fivemiddle_finger_mid_finger_flexion_peakmiddle_finger_mid_finger_flexion_average_rep_two_to_fivering_finger_mid_finger_flexion_peakring_finger_mid_finger_flexion_average_rep_two_to_fivelittle_finger_mid_finger_flexion_peaklittle_finger_mid_finger_flexion_average_rep_two_to_fiveulnar_deviation_peakulnar_deviation_average_rep_two_to_fiveradial_deviation_peakradial_deviation_average_rep_two_to_five |
% of 1RM Target Training (A / B / C Days)
For each exercise these categories report the target force, the achieved average force, and the average as a percentage of the 1RM.
| Category | Data fields |
|---|---|
percentage_of_1rm_target_a_day |
target_percentage_for_sessionfour_finger_finger_tip_flexion_targetfour_finger_finger_tip_flexion_averagefour_finger_finger_tip_percentage_of_target_one_rmindex_finger_finger_tip_flexion_targetindex_finger_finger_tip_flexion_averageindex_finger_finger_tip_flexion_percentage_of_target_one_rmmiddle_finger_finger_tip_flexion_targetmiddle_finger_finger_tip_flexion_averagemiddle_finger_finger_tip_flexion_percentage_of_target_one_rmring_finger_finger_tip_flexion_targetring_finger_finger_tip_flexion_averagering_finger_finger_tip_flexion_percentage_of_target_one_rmlittle_finger_finger_tip_flexion_targetlittle_finger_finger_tip_flexion_averagelittle_finger_finger_tip_flexion_percentage_of_target_one_rmulnar_deviation_targetulnar_deviation_averageulnar_deviation_percentage_of_target_one_rmStrength sessions only: four_finger_finger_tip_flexion_peak, ulnar_deviation_peak |
percentage_of_1rm_target_b_day |
target_percentage_for_sessionfour_finger_extension_targetfour_finger_extension_averagefour_finger_extension_percentage_of_target_one_rmindex_finger_extension_targetindex_finger_extension_averageindex_finger_extension_percentage_of_target_one_rmmiddle_finger_extension_targetmiddle_finger_extension_averagemiddle_finger_extension_percentage_of_target_one_rmring_finger_extension_targetring_finger_extension_averagering_finger_extension_percentage_of_target_one_rmlittle_finger_extension_targetlittle_finger_extension_averagelittle_finger_extension_percentage_of_target_one_rmradial_deviation_targetradial_deviation_averageradial_deviation_percentage_of_target_one_rmStrength sessions only: four_finger_extension_peak, radial_deviation_peak |
percentage_of_1rm_target_c_day |
target_percentage_for_sessionfour_finger_mid_finger_flexion_targetfour_finger_mid_finger_flexion_averagefour_finger_mid_finger_flexion_percentage_of_target_one_rmindex_finger_mid_finger_flexion_targetindex_finger_mid_finger_flexion_averageindex_finger_mid_finger_flexion_percentage_of_target_one_rmmiddle_finger_mid_finger_flexion_targetmiddle_finger_mid_finger_flexion_averagemiddle_finger_mid_finger_flexion_percentage_of_target_one_rmring_finger_mid_finger_flexion_targetring_finger_mid_finger_flexion_averagering_finger_mid_finger_flexion_percentage_of_target_one_rmlittle_finger_mid_finger_flexion_targetlittle_finger_mid_finger_flexion_averagelittle_finger_mid_finger_flexion_percentage_of_target_one_rmulnar_deviation_targetulnar_deviation_averageulnar_deviation_percentage_of_target_one_rmMost sessions also: radial_deviation_target, radial_deviation_average, radial_deviation_percentage_of_target_one_rmStrength sessions only: four_finger_mid_finger_flexion_peak, ulnar_deviation_peak |
Other % of 1RM Target Protocols
| Category | Data fields |
|---|---|
long_hold_percentage_of_1rm_target |
target_percentage_for_sessionfour_finger_finger_tip_flexion_targetfour_finger_finger_tip_flexion_averagefour_finger_finger_tip_flexion_avg_to_mvculnar_deviation_targetulnar_deviation_averageulnar_deviation_avg_to_mvcfour_finger_mid_finger_flexion_targetfour_finger_finger_middle_flexion_averagefour_finger_finger_middle_flexion_avg_to_mvcindex_little_finger_middle_flexion_targetindex_little_finger_middle_flexion_averageindex_little_finger_middle_flexion_avg_to_mvc |
power_percentage_of_1rm_target |
target_percentage_for_sessionim_finger_tip_flexion_targetim_finger_tip_flexion_avgim_finger_tip_flexion_avg_to_mvcaverage_total_peak_forceaverage_index_peak_forceaverage_middle_peak_force |
endurance_percentage_of_1rm_target |
target_percentage_for_sessionim_finger_tip_flexion_maxim_finger_tip_flexion_minim_finger_tip_flexion_avgim_finger_tip_flexion_avg_to_mvcwrist_ulnar_maxwrist_ulnar_minwrist_ulnar_avgwrist_ulnar_avg_to_mvc |
Endurance
| Category | Data fields |
|---|---|
endurance_test |
highest_forcelowest_forceaverage_forceexercise_two_highest_forceexercise_two_lowest_forceexercise_two_average_force |
endurance_training |
Same fields as endurance_test. |
Rate of Force Development
| Category | Data fields |
|---|---|
rate_of_force_test |
exercise_two_average_forceexercise_two_average_force_ms39exercise_two_average_force_ms176average_total_peak_forceindex_finger_average_forceindex_finger_average_force_ms39index_finger_average_force_ms176average_index_peak_forcemiddle_finger_average_forcemiddle_finger_average_force_ms39middle_finger_average_force_ms176average_middle_peak_force |
rate_of_force_test_two_fingers_with_five_reps |
Same fields as rate_of_force_test. |
four_finger_rate_of_force_test |
exercise_total_average_forceexercise_total_average_force_ms39exercise_total_average_force_ms176average_total_peak_forceFor each of index, middle, ring, little:<finger>_finger_average_force<finger>_finger_average_force_ms39<finger>_finger_average_force_ms176average_<finger>_peak_force |
rate_of_force_development_training_cycle |
exercise_one_peak_forceexercise_two_average_forceexercise_two_average_force_ms39exercise_two_average_force_ms176exercise_two_average_total_peak_forceexercise_two_average_force_ms176_to_rm1exercise_two_index_finger_average_forceexercise_two_index_finger_average_force_ms39exercise_two_average_index_peak_forceexercise_two_middle_finger_average_forceexercise_two_middle_finger_average_force_ms39exercise_two_average_middle_peak_forceexercise_three_average_peak_force |
rate_of_force_development_training_one_session |
Same fields as rate_of_force_development_training_cycle. |
Scored Tests
Besides force metrics, the data of scored tests includes the player's height, expected_peak_velocity, the protocol variant (string or null), and the scoring results (*_actual, *_target, *_points, score).
Target, points, and score fields are omitted or null when the player has no height or expected_peak_velocity set.
| Category | Data fields |
|---|---|
readiness_test |
four_finger_averagefour_finger_peakfour_finger_high_low_varianceulnar_deviation_averageulnar_deviation_peakulnar_deviation_high_low_varianceScoring: variant, height, expected_peak_velocity, flexion_peak_actual, flexion_peak_points, flexion_avg_to_peak_actual, flexion_avg_to_peak_points, flexion_high_low_actual, flexion_high_low_points, flexion_safe_target, flexion_desired_target, ulnar_peak_actual, ulnar_peak_points, ulnar_avg_to_peak_actual, ulnar_avg_to_peak_points, ulnar_high_low_actual, ulnar_high_low_points, ulnar_safe_target, ulnar_desired_target, mid_finger_safe_target, mid_finger_desired_target, score |
new_readiness_test |
four_finger_averagefour_finger_peakfour_finger_high_low_varianceulnar_deviation_averageulnar_deviation_peakulnar_deviation_high_low_variancemid_finger_averagemid_finger_peakScoring: all readiness_test scoring fields, plus mid_finger_peak_actual, mid_finger_peak_points, mid_finger_avg_to_peak_actual, mid_finger_avg_to_peak_points, mid_finger_high_low_actual, mid_finger_high_low_points |
throwers_rapid_strength_test |
variantprotocol_name (always "throwers_rapid_strength_test")heightexpected_peak_velocityflexion_actual, flexion_target, flexion_points, flexion_points_weightedmid_finger_actual, mid_finger_target, mid_finger_points, mid_finger_points_weightedulnar_actual, ulnar_target, ulnar_points, ulnar_points_weightedscorescored_velocity |
rapid_flexion_test |
variantheightexpected_peak_velocityflexion_actual, flexion_target, flexion_pointsmid_finger_actual, mid_finger_target, mid_finger_pointssupported_velocity_mphsupported_velocity_percentageFor each of index, middle, ring, little: <finger>_finger_flexion_actual, <finger>_finger_mid_finger_actual |
Swing Speed
The fields depend on the day of the swing speed program.
| Category | Data fields |
|---|---|
swing_speed |
Day A: four_finger_finger_tip_flexion_peak, four_finger_finger_tip_flexion_average, ulnar_deviation_peak, ulnar_deviation_averageDay B: four_finger_finger_tip_extension_peak, four_finger_finger_tip_extension_average, radial_deviation_peak, radial_deviation_averageDay C: four_finger_finger_middle_flexion_peak, four_finger_finger_middle_flexion_average, ulnar_deviation_peak, ulnar_deviation_average, radial_deviation_peak, radial_deviation_average |
Parameter Validation
Date Ranges
| Endpoint | Default Start | Default End | Max Range |
|---|---|---|---|
/api/histories |
Exactly 7 days ago | Now | None |
All dates must follow ISO 8601 format:
✅ Example: 2025-11-03
❌ Invalid: 11/03/2025, 03-11-25
A date in any other format causes the request to fail. Always send YYYY-MM-DD.
Error Handling
HTTP Status Codes
- 200 OK: Request successful
- 401 Unauthorized: Missing or invalid API key (empty response body)
- 500 Internal Server Error: Server error
Examples
Example 1: Histories from the last 7 days
GET /api/histories
api-key: <your_api_key>
Example 2: Histories for a specific date range
GET /api/histories?start_date=2025-10-01&end_date=2025-10-31
api-key: <your_api_key>
Example 3: Histories for a single day
GET /api/histories?start_date=2025-11-03&end_date=2025-11-03
api-key: <your_api_key>
Example 4: cURL
curl -H "api-key: <your_api_key>" \
"https://<your-flexpro-grip-host>/api/histories?start_date=2025-11-01&end_date=2025-11-07"