How to Get Tests

As of January 01, 2026, the use of `get_tests_…` functions have been superseded in favor of the expanded usage of `get_tests`. The base `get_tests` function has been expanded to accept all arguments from the other `get_tests_…` variations.

The get_tests() function is the primary tool for querying performance data from the Hawkin Dynamics Cloud. In v2.0, this single function replaces all previous variations, providing a unified way to filter by date, athlete, team, group, or test type.

1. Basic Usage

The simplest way to use get_tests() is to provide a date range. You can use standard date strings ("YYYY-MM-DD") or Unix timestamps.

library(hawkinR)
hd_connect()

# Call all tests
all_tests <- get_tests()

# Pull all tests from the start of 2023 to present
tests <- get_tests(from = "2023-01-01")

2. Advanced Filtering

You can combine multiple filters to narrow down your dataset. When multiple filters are provided, the API returns trials that meet all criteria.

Filter by Test Type

To isolate specific movements (e.g., Countermovement Jumps), use the typeId.

# Pull only CMJ tests
cmj_data <- get_tests(typeId = "7nNduHeM5zETPjHxvm7s")

# Test type argument also excepts type name or abbreviation

# Squat Jump
sj_data <- get_tests(typeId = "SJ")

# Iso tests
iso_data <- get_tests(typeId = "Isometric Test")

Filter by Athletes, Teams, or Groups

First, it is important to remember a few specifics of the HD athlete data structure. All unique entities have unique IDs. This includes athletes, tests types, teams, and groups. Each athlete MUST be a part of a team, but MAY optionally be in a group. Also, athletes can be a part of multiple teams and multiple groups. To see which teams and/or groups an athlete is a part of, you can find this in the data frame returned from get_athletes. For more information on this, you can go to the Getting Started page for specifics.

# Store player info in object called roster. 
# 'inactive' is default to FALSE. Set to TRUE if you want to include inactive athletes.
roster <- get_athletes(inactive = FALSE)
id name active teams groups external
0kEjAzSLpBwUZc4Yp2Ov Athlete One TRUE 09u20ij0dj0 0j20j09jd9ud0j AMS:dj0203j0dj,GPS:md029j3209j2
1E1zYBv0CKbrKnsKz1vj Player Two TRUE 09u20ij0dj0 0j20j09jd9ud0j,92d2098d02j0 AMS:oin208ju09,GPS:od093j32
1lXEZKkNuNwvMLXiqFRr Person Three TRUE 9308dj209dj AMS:j029j0jd20j,GPS:0d28j098h3

You can filter for a specific athlete, or an entire cohort using teamId or groupId. In v2.0, these fields accept either a single ID string or a vector of IDs.


# Tests By Athlete
athelte <- roster$id[roster$name == "Some Athlete"]
ath_tests <-  get_tests(athleteId = athlete)

# Pull Tests by team
team_ids <- c("team_id_1", "team_id_2")
cohort_data <- get_tests(teamId = team_ids)

It is important to note that test can only be filtered by a singular parameter and a time frame. This means you CAN NOT combine arguments for teams and groups or athlete. Queries can only be made with from, to, and teams OR groups OR athlete.

3. The “Sync” Parameter

For developers building local databases, the sync parameter allows you to pull data based on when it was uploaded/modified rather than when the test occurred. This is essential for Incremental Refresh logic.

# Pull everything synced to the cloud in the last 24 hours
last_24h <- as.numeric(Sys.time()) - 86400
new_data <- get_tests(from = last_24h, sync = TRUE)

4. Data Structure

The returned data frame is automatically processed using internal prep functions (AthletePrep and TestTypePrep). The columns are organized into four logical sections:

  1. Trial Info: Basic trial metadata (ID, timestamp, etc.)

  2. Test Type Info: Details about the movement performed.

  3. Athlete Info: Details about the athlete who performed the test.

  4. Metrics: All performance metrics (Force, Velocity, Power, etc.) with clean names.

5. Handling Inactive Data

By default, get_tests() only returns trials marked as “Active.” If you need to include deleted or hidden trials for auditing purposes, set includeInactive = TRUE.

# Include inactive/deleted tests in the response
all_history <- get_tests(from = "2023-01-01", includeInactive = TRUE)

All of the test trials have there own unique ID. This testId is what is used in the get_forcetime function to call in the raw data from that trial. See Accessing Force-Time Data of A Test for more information.