Filtering Metrics

Learn how to use custom query parameters to filter export data API results for specific metrics and rows.

Using Custom Query Parameters

The API allows you to include additional query parameters to filter results of specific columns based on the metrics parameter and rows based on the row_filter_column parameter.

Parameter	Type	Required	Description
metrics	Array of metric names	Optional	If provided, only returns the specified columns instead of every metric.
row_filter_column	String	Optional	Controls which rows are returned in the response.

Note: Details on row_filter_column are below.

Value	Result	Example Use Case
Not provided	Return all time-series rows	Default behavior
”frame”	Return a single row where frame=0	For getting the start of the movement.
Event column name	Return a single row where that column = 0	For getting values at a specific event (ex: peak_event).

Examples of Usage

Here are some examples to demonstrate how to use custom attributes effectively:

1. Filter by metrics only
   If you want to retrieve specific metrics such as peak_event and peak_power:

   curl --request POST \
   --url https://api.uplift.ai/v1/data/export \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data '{
     "startTime": 123,
     "endTime": 123,
     "athletes": [
       "<string>"
     ],
     "activity": "agility",
     "movement": "cutting",
     "dateMode": "last_modified",
     "metrics": [
       "peak_event",
       "peak_power"
     ]
   }'
   

2. Filter by metrics and row_filter_column
   You can combine metrics and row_filter_column to refine your search further. For example, if you want to retrieve the row of peak_event and peak_power for the cutting movement at the turn_event equal to 0:

   curl --request POST \
   --url https://api.uplift.ai/v1/data/export \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data '{
     "startTime": 123,
     "endTime": 123,
     "athletes": [
       "<string>"
     ],
     "activity": "agility",
     "movement": "cutting",
     "dateMode": "last_modified",
     "metrics": [
       "peak_event",
       "peak_power"
     ],
     "row_filter_column": "turn_event"
   }'
   

Important Notes

1. Metrics Availability:
   Verify that all requested metrics exist in the dataset before filtering. If any specified metric is not available, the export data job will fail. Check the errorMessage in the response for details about any non-existent columns when using the metrics parameter.

   {
      "jobId": "17eafc5c-2e4d-44e9-bdfe-7617591a5f00",
      "status": "FAILED",
      "errorMessage": "Column 'peak_power' not found",
      "createdAt": "2025-05-02T17:40:51.988Z",
      "completedAt": "2025-05-02T17:40:52.592Z"
   }
   

   On the summary data access level, a metric that exists only in the full dataset is rejected up front with a 400 on the POST /data/export call — “One or more requested metrics are only available with full data access…” — rather than as an asynchronous FAILED job. See Data access level.

2. Row Filter Column:
   Ensure the specified row filter column exists in the export data. If the column doesn’t exist, the export data job will fail. The response errorMessage will indicate the column specified in the row_filter_column parameter is invalid.

   Note that row filtering only supports values equal to 0. In theory, only a single row is returned for each session. If no rows have a value of 0 for the specified row filter column, the query may return an empty result set.

   On the summary data access level, row_filter_column is not applicable — a summary export is already one row per capture — so it is rejected up front with a 400 on the POST /data/export call (“The row_filter_column parameter is not applicable on the summary data tier…”) rather than running the export.