Skip to main content

/o/analytics/metric

Endpoint​

/o/analytics/metric

Overview​

Returns one metric breakdown array for the requested metric key.

Authentication​

  • API Key (parameter): api_key=YOUR_API_KEY
  • Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
  • Auth Token (header): countly-token: YOUR_AUTH_TOKEN

Permissions​

  • Requires read access to feature core for the target app.

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or use auth_token)Dashboard API authentication key.
auth_tokenStringYes (or use api_key)Dashboard auth token.
app_idStringYesApp ID (24-char hex).
metricStringYesMetric key to read (for example countries, carriers, platforms, resolutions, devices, app_versions).
periodStringNoRequested period.
timezoneStringNoOptional timezone override.
timestampNumberNoOptional reference timestamp.

Parameter Semantics​

  • If metric is missing, request fails.
  • If metric does not map to a supported collection path, response is an empty array ([]).
  • Common metric mappings:
    • countries -> users aggregate countries
    • platforms/os -> device details OS
    • resolutions -> device details resolutions
    • carriers -> carriers aggregate

Configuration Impact​

SettingDefaultAffectsUser-visible impact
api.total_userstrueUnique-user correctionWhen disabled, total-user correction path is skipped.
api.metric_changestrueCorrection historyWhen disabled, metric-change historical adjustments are not applied.

Response​

Success Response​

[
  {"_id": "US", "t": 10, "n": 0, "u": 3},
  {"_id": "DE", "t": 4, "n": 0, "u": 2},
  {"_id": "NZ", "t": 3, "n": 0, "u": 2}
]

Response Fields​

FieldTypeDescription
[]ArrayMetric rows for the selected metric.
[] ._idStringSegment value (for example country code, carrier name, platform).
[] .tNumberTotal count for segment.
[] .nNumberNew-user count for segment.
[] .uNumberUnique-user count for segment.

Error Responses​

Status Code: 400 Bad Request

{"result":"Must provide metric"}

Status Code: 400 Bad Request

{"result":"Missing parameter \"app_id\""}

Status Code: 401 Unauthorized

{"result":"User does not have right"}

Behavior/Processing​

Behavior Modes​

ModeTriggerProcessing PathResponse Shape
Supported metricmetric maps to a known collectionResolves metric mapping and returns extracted metric rows (with total-user correction when enabled).Raw root array of metric rows.
Unsupported metricmetric does not map to a collectionStops after mapping check without querying metric data.Raw root empty array: [].

Impact on Other Data​

  • Read-only endpoint.

Audit & System Logs​

  • No /systemlogs action is emitted by this endpoint.

Database Collections​

CollectionUsed forData touched by this endpoint
countly.membersAuthentication and permission validationReads member record by api_key or auth_token to verify read access.
countly.appsApp context validationReads app record (timezone, app state) for the requested app_id.
countly.users{appId}Countries/session/user metric sourceRead for user-level aggregate metrics.
countly.device_details{appId}Platform/resolution/app-version metric sourceRead for device aggregate metrics.
countly.devices{appId}Device/manufacturer metric sourceRead for device category metrics.
countly.cities{appId}City metric sourceRead for city-based metric output.
countly.app_users{appId}Total-user correction baselineRead during total-user correction flows.
countly.metric_changes{appId}Correction historyRead when metric-change correction is enabled.

Examples​

Example 1: Read countries metric​

/o/analytics/metric?
  api_key=YOUR_API_KEY&
  app_id=6991c75b024cb89cdc04efd2&
  metric=countries&
  period=7days

Example 2: Read platforms metric​

/o/analytics/metric?
  api_key=YOUR_API_KEY&
  app_id=6991c75b024cb89cdc04efd2&
  metric=platforms&
  period=30days

Operational Considerations​

  • High-cardinality metrics produce larger result arrays.

Limitations​

  • Unsupported metric keys return [] instead of a validation error.

Last Updated​

2026-02-17