Performance Metrics

Query telemetry data with custom aggregations and filters for analytics. This endpoint builds ClickHouse SQL queries from request parameters to provide flexible data analysis.

Endpoint

POST /v1/interactions/performance-metric/distribution

Authentication

This endpoint requires authentication using JWT tokens. Include the token in the Authorization header:

authorization: Bearer {token}

---

Performance Metric Distribution

Queries telemetry data with custom aggregations and filters for analytics. Builds ClickHouse SQL queries from request parameters.

Endpoint: POST /v1/interactions/performance-metric/distribution

Request Headers:

Header	Value
authorization	Bearer {token}
Content-Type	application/json

Request Body

Request Fields:

Field	Type	Required	Description
dataType	string	✅ Yes	ClickHouse table to query: TRACES, METRICS, LOGS, or EXCEPTIONS
timeRange	object	✅ Yes	ISO-8601 UTC timestamps with start and end fields
select	array	✅ Yes	Array of metric functions to calculate
filters	array	❌ No	Array of WHERE clause conditions
groupBy	array	❌ No	Array of field names or aliases to group by
orderBy	array	❌ No	Array of sorting specifications
limit	number	❌ No	Maximum rows to return (default: 100)

Time Range Object:

Field	Type	Required	Description
start	string	✅ Yes	ISO-8601 UTC start timestamp
end	string	✅ Yes	ISO-8601 UTC end timestamp

Select Item Object:

Field	Type	Required	Description
function	string	✅ Yes	Predefined metric function (see below)
param	object	❌ No	Function-specific parameters
alias	string	❌ No	Custom name for result column

Filter Object:

Field	Type	Required	Description
field	string	✅ Yes	Column name to filter on (e.g., "span.name", "page.url")
operator	string	✅ Yes	Comparison operator: IN, LIKE, EQ, ADDITIONAL
value	array	✅ Yes	Array of values to match against

Order By Object:

Field	Type	Required	Description
field	string	✅ Yes	Field or alias name to sort by
direction	string	✅ Yes	Sort direction: ASC or DESC

Available Functions

Function	Description	Parameters
APDEX	Calculates average APDEX score from span attributes, excluding error status codes	None
DURATION_P99	99th percentile duration in seconds, excluding errors	None
DURATION_P95	95th percentile duration in seconds, excluding errors	None
DURATION_P50	50th percentile (median) duration in seconds, excluding errors	None
CRASH	Count of crash events (device.crash)	None
ANR	Count of Application Not Responding events (device.anr)	None
FROZEN_FRAME	Sum of frozen frame counts from span attributes	None
ANALYSED_FRAME	Sum of analysed frame counts from span attributes	None
UNANALYSED_FRAME	Sum of unanalysed frame counts from span attributes	None
COL	Selects a column directly	param.field: Column name
TIME_BUCKET	Groups timestamps into time buckets	param.bucket: Bucket size (e.g., "1d", "1h"); param.field: Timestamp column name
CUSTOM	Executes custom ClickHouse expression	param.expression: SQL expression string
INTERACTION_SUCCESS_COUNT	Count of successful interactions (non-error status codes)	None
INTERACTION_ERROR_COUNT	Count of failed interactions (error status codes)	None
INTERACTION_ERROR_DISTINCT_USERS	Count of distinct users who encountered errors	None
USER_CATEGORY_EXCELLENT	Count of users in EXCELLENT category	None
USER_CATEGORY_GOOD	Count of users in GOOD category	None
USER_CATEGORY_AVERAGE	Count of users in AVERAGE category	None
USER_CATEGORY_POOR	Count of users in POOR category	None
NET_0	Sum of network connection errors (network.0 events)	None
NET_2XX	Sum of successful HTTP responses (2xx status codes)	None
NET_3XX	Sum of redirect responses (3xx status codes)	None
NET_4XX	Sum of client error responses (4xx status codes)	None
NET_5XX	Sum of server error responses (5xx status codes)	None
ARR_TO_STR	Converts array to comma-separated string	param.field: Array column name

Example Request

POST /v1/interactions/performance-metric/distribution
authorization: Bearer {token}
Content-Type: application/json

{
  "dataType": "TRACES",
  "timeRange": {
    "start": "2025-11-07T08:40:00Z",
    "end": "2025-11-12T14:40:00Z"
  },
  "select": [
    { "function": "COL", "param": {"field": "os.version"}, "alias": "osVersion"},
    { "function": "DURATION_P99", "alias": "duration_p99"},
    { "function": "APDEX"},
    { "function": "TIME_BUCKET", "param": {"bucket": "1d", "field": "Timestamp"}, "alias": "t1"},
    { "function": "CUSTOM", "param": { "expression": "countIf(StatusCode!='Error')"}, "alias": "success_count"}
  ],
  "filters": [
    { "field": "span.name", "operator": "IN", "value": ["page_load"] },
    { "field": "page.url", "operator": "LIKE", "value": ["https%://my-store.com/checkout/%"] }
  ],
  "groupBy": [
    "osVersion"
  ],
  "orderBy": [
    { "field": "t1", "direction": "ASC" },
    { "field": "apdex", "direction": "ASC" }
  ],
  "limit": 1000
}

Response

Response Fields:

Field	Type	Description
status	number	HTTP status code
data.fields	string[]	Column names in the result set
data.rows	array[]	Array of result rows, each row is an array matching field order
error	string | null	Error message if request failed, null on success

Example Response:

{
  "status": 200,
  "data": {
    "fields": ["osVersion", "duration_p99", "apdex", "t1", "success_count"],
    "rows": [
      ["1.0_1", "0.547", "0.68", "2025-11-08T08:40:00Z", "24"],
      ["1.0_2", "0.566", "0.677", "2025-11-09T08:40:00Z", "23"]
    ]
  },
  "error": null
}