> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uplift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:
   ```bash theme={null}
   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:
   ```bash theme={null}
   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.
   ```json theme={null}
   {
      "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"
   }
   ```

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.