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

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 category of a history identifies the protocol it belongs to and determines which fields appear in its data object.

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_peak
index_finger_finger_tip_flexion_peak
middle_finger_finger_tip_flexion_peak
ring_finger_finger_tip_flexion_peak
little_finger_finger_tip_flexion_peak
four_finger_extension_peak
index_finger_extension_peak
middle_finger_extension_peak
ring_finger_extension_peak
little_finger_extension_peak
four_finger_mid_finger_flexion_peak
index_finger_mid_finger_flexion_peak
middle_finger_mid_finger_flexion_peak
ring_finger_mid_finger_flexion_peak
little_finger_mid_finger_flexion_peak
ulnar_deviation_peak
radial_deviation_peak
rehab_strength_test Same fields as strength_test.
rapid_strength_test four_finger_finger_tip_flexion_peak
four_finger_finger_tip_extension_peak
four_finger_mid_finger_flexion_peak
ulnar_deviation_peak
radial_deviation_peak

Strength Training (A / B / C Days)

Category Data fields
training_a_day four_finger_finger_tip_flexion_peak
four_finger_finger_tip_flexion_average_rep_two_to_five
index_finger_finger_tip_flexion_peak
index_finger_finger_tip_flexion_average_rep_two_to_five
middle_finger_finger_tip_flexion_peak
middle_finger_finger_tip_flexion_average_rep_two_to_five
ring_finger_finger_tip_flexion_peak
ring_finger_finger_tip_flexion_average_rep_two_to_five
little_finger_finger_tip_flexion_peak
little_finger_finger_tip_flexion_average_rep_two_to_five
ulnar_deviation_peak
ulnar_deviation_average_rep_two_to_five
training_b_day four_finger_extension_peak
four_finger_extension_average_rep_two_to_five
index_finger_extension_peak
index_finger_extension_average_rep_two_to_five
middle_finger_extension_peak
middle_finger_extension_average_rep_two_to_five
ring_finger_extension_peak
ring_finger_extension_average_rep_two_to_five
little_finger_extension_peak
little_finger_extension_average_rep_two_to_five
radial_deviation_peak
radial_deviation_average_rep_two_to_five
training_c_day four_finger_mid_finger_flexion_peak
four_finger_mid_finger_flexion_average_rep_two_to_five
index_finger_mid_finger_flexion_peak
index_finger_mid_finger_flexion_average_rep_two_to_five
middle_finger_mid_finger_flexion_peak
middle_finger_mid_finger_flexion_average_rep_two_to_five
ring_finger_mid_finger_flexion_peak
ring_finger_mid_finger_flexion_average_rep_two_to_five
little_finger_mid_finger_flexion_peak
little_finger_mid_finger_flexion_average_rep_two_to_five
ulnar_deviation_peak
ulnar_deviation_average_rep_two_to_five
radial_deviation_peak
radial_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_session
four_finger_finger_tip_flexion_target
four_finger_finger_tip_flexion_average
four_finger_finger_tip_percentage_of_target_one_rm
index_finger_finger_tip_flexion_target
index_finger_finger_tip_flexion_average
index_finger_finger_tip_flexion_percentage_of_target_one_rm
middle_finger_finger_tip_flexion_target
middle_finger_finger_tip_flexion_average
middle_finger_finger_tip_flexion_percentage_of_target_one_rm
ring_finger_finger_tip_flexion_target
ring_finger_finger_tip_flexion_average
ring_finger_finger_tip_flexion_percentage_of_target_one_rm
little_finger_finger_tip_flexion_target
little_finger_finger_tip_flexion_average
little_finger_finger_tip_flexion_percentage_of_target_one_rm
ulnar_deviation_target
ulnar_deviation_average
ulnar_deviation_percentage_of_target_one_rm
Strength sessions only: four_finger_finger_tip_flexion_peak, ulnar_deviation_peak
percentage_of_1rm_target_b_day target_percentage_for_session
four_finger_extension_target
four_finger_extension_average
four_finger_extension_percentage_of_target_one_rm
index_finger_extension_target
index_finger_extension_average
index_finger_extension_percentage_of_target_one_rm
middle_finger_extension_target
middle_finger_extension_average
middle_finger_extension_percentage_of_target_one_rm
ring_finger_extension_target
ring_finger_extension_average
ring_finger_extension_percentage_of_target_one_rm
little_finger_extension_target
little_finger_extension_average
little_finger_extension_percentage_of_target_one_rm
radial_deviation_target
radial_deviation_average
radial_deviation_percentage_of_target_one_rm
Strength sessions only: four_finger_extension_peak, radial_deviation_peak
percentage_of_1rm_target_c_day target_percentage_for_session
four_finger_mid_finger_flexion_target
four_finger_mid_finger_flexion_average
four_finger_mid_finger_flexion_percentage_of_target_one_rm
index_finger_mid_finger_flexion_target
index_finger_mid_finger_flexion_average
index_finger_mid_finger_flexion_percentage_of_target_one_rm
middle_finger_mid_finger_flexion_target
middle_finger_mid_finger_flexion_average
middle_finger_mid_finger_flexion_percentage_of_target_one_rm
ring_finger_mid_finger_flexion_target
ring_finger_mid_finger_flexion_average
ring_finger_mid_finger_flexion_percentage_of_target_one_rm
little_finger_mid_finger_flexion_target
little_finger_mid_finger_flexion_average
little_finger_mid_finger_flexion_percentage_of_target_one_rm
ulnar_deviation_target
ulnar_deviation_average
ulnar_deviation_percentage_of_target_one_rm
Most sessions also: radial_deviation_target, radial_deviation_average, radial_deviation_percentage_of_target_one_rm
Strength 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_session
four_finger_finger_tip_flexion_target
four_finger_finger_tip_flexion_average
four_finger_finger_tip_flexion_avg_to_mvc
ulnar_deviation_target
ulnar_deviation_average
ulnar_deviation_avg_to_mvc
four_finger_mid_finger_flexion_target
four_finger_finger_middle_flexion_average
four_finger_finger_middle_flexion_avg_to_mvc
index_little_finger_middle_flexion_target
index_little_finger_middle_flexion_average
index_little_finger_middle_flexion_avg_to_mvc
power_percentage_of_1rm_target target_percentage_for_session
im_finger_tip_flexion_target
im_finger_tip_flexion_avg
im_finger_tip_flexion_avg_to_mvc
average_total_peak_force
average_index_peak_force
average_middle_peak_force
endurance_percentage_of_1rm_target target_percentage_for_session
im_finger_tip_flexion_max
im_finger_tip_flexion_min
im_finger_tip_flexion_avg
im_finger_tip_flexion_avg_to_mvc
wrist_ulnar_max
wrist_ulnar_min
wrist_ulnar_avg
wrist_ulnar_avg_to_mvc

Endurance

Category Data fields
endurance_test highest_force
lowest_force
average_force
exercise_two_highest_force
exercise_two_lowest_force
exercise_two_average_force
endurance_training Same fields as endurance_test.

Rate of Force Development

Category Data fields
rate_of_force_test exercise_two_average_force
exercise_two_average_force_ms39
exercise_two_average_force_ms176
average_total_peak_force
index_finger_average_force
index_finger_average_force_ms39
index_finger_average_force_ms176
average_index_peak_force
middle_finger_average_force
middle_finger_average_force_ms39
middle_finger_average_force_ms176
average_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_force
exercise_total_average_force_ms39
exercise_total_average_force_ms176
average_total_peak_force
For each of index, middle, ring, little:
<finger>_finger_average_force
<finger>_finger_average_force_ms39
<finger>_finger_average_force_ms176
average_<finger>_peak_force
rate_of_force_development_training_cycle exercise_one_peak_force
exercise_two_average_force
exercise_two_average_force_ms39
exercise_two_average_force_ms176
exercise_two_average_total_peak_force
exercise_two_average_force_ms176_to_rm1
exercise_two_index_finger_average_force
exercise_two_index_finger_average_force_ms39
exercise_two_average_index_peak_force
exercise_two_middle_finger_average_force
exercise_two_middle_finger_average_force_ms39
exercise_two_average_middle_peak_force
exercise_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_average
four_finger_peak
four_finger_high_low_variance
ulnar_deviation_average
ulnar_deviation_peak
ulnar_deviation_high_low_variance
Scoring: 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_average
four_finger_peak
four_finger_high_low_variance
ulnar_deviation_average
ulnar_deviation_peak
ulnar_deviation_high_low_variance
mid_finger_average
mid_finger_peak
Scoring: 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 variant
protocol_name (always "throwers_rapid_strength_test")
height
expected_peak_velocity
flexion_actual, flexion_target, flexion_points, flexion_points_weighted
mid_finger_actual, mid_finger_target, mid_finger_points, mid_finger_points_weighted
ulnar_actual, ulnar_target, ulnar_points, ulnar_points_weighted
score
scored_velocity
rapid_flexion_test variant
height
expected_peak_velocity
flexion_actual, flexion_target, flexion_points
mid_finger_actual, mid_finger_target, mid_finger_points
supported_velocity_mph
supported_velocity_percentage
For 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_average
Day B: four_finger_finger_tip_extension_peak, four_finger_finger_tip_extension_average, radial_deviation_peak, radial_deviation_average
Day 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"