Guides
Guides

Query Parameters

Filtering, pagination, and aggregation options for the Data Access API

Query Parameters

All Data Access API endpoints support common query parameters for filtering, pagination, and aggregation.

Pagination

Control how many results are returned and which page to fetch.

ParameterTypeDescriptionDefault
pageIntegerPage number (1-indexed)1
page_sizeIntegerResults per page (max 1000)50

Example

curl "https://api.uxcam.com/v2/session" \
  -H "X-App-Id: YOUR_APP_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -G \
  --data-urlencode 'page=2' \
  --data-urlencode 'page_size=100'

Filters

Narrow results to specific criteria. Filters are passed as a JSON array.

Filter Structure

{
  "attribute": "attribute_name",
  "operator": "operator_type",
  "value": "filter_value"
}

Common Operators

OperatorDescriptionExample Value
equalExact match"USA"
not_equalNot equal"USA"
inMatch any in list["USA", "UK", "CA"]
not_inMatch none in list["test", "demo"]
greater_thanGreater than100
less_thanLess than100
between_datesDate range{"lower": "2024-01-01", "upper": "2024-01-31"}

See Filter Operators for the complete list.

Example

# Sessions from USA with duration > 60 seconds
curl "https://api.uxcam.com/v2/session" \
  -H "X-App-Id: YOUR_APP_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -G \
  --data-urlencode 'filters=[
    {"attribute":"device_country","operator":"equal","value":"USA"},
    {"attribute":"session_duration","operator":"greater_than","value":60}
  ]'

Group By (Analytics Only)

Aggregate results by specific attributes. Used with /analytics endpoints.

Structure

{
  "attribute": "attribute_name",
  "max_group_number": 50
}

Example

# Session analytics grouped by device model
curl "https://api.uxcam.com/v2/session/analytics" \
  -H "X-App-Id: YOUR_APP_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -G \
  --data-urlencode 'group_by=[{"attribute":"device_model","max_group_number":20}]'

Common Group Attributes

AttributeDescription
device_modelGroup by device model
device_platformGroup by iOS/Android
device_countryGroup by country
app_versionGroup by app version
session_uploadedon_dayGroup by day
session_uploaded_weekGroup by week
session_uploaded_monthGroup by month

Aggregation (Analytics Only)

Specify which metrics to calculate.

Example

curl "https://api.uxcam.com/v2/session/analytics" \
  -H "X-App-Id: YOUR_APP_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -G \
  --data-urlencode 'aggregation=[{"attribute":"session_count"}]'

Common Aggregations

AttributeDescription
session_countTotal sessions
session_unique_user_countUnique users
avg_session_durationAverage session length
avg_session_gesture_countAverage interactions

Comparison (Analytics Only)

Compare current period to previous period.

ParameterTypeDescription
comparisonInteger1 = compare to previous period

Example

# Compare current month to previous month
curl "https://api.uxcam.com/v2/session/analytics" \
  -H "X-App-Id: YOUR_APP_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -G \
  --data-urlencode 'comparison=1'

Date Range

Filter by date using the date_range attribute.

Example

curl "https://api.uxcam.com/v2/session" \
  -H "X-App-Id: YOUR_APP_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -G \
  --data-urlencode 'filters=[
    {
      "attribute": "date_range",
      "operator": "between_dates",
      "value": {
        "lower": "2024-01-01T00:00:00Z",
        "upper": "2024-01-31T23:59:59Z"
      }
    }
  ]'

See Also