App Utilization Detail

Approved

This endpoint is approved but has not been implemented yet.

GET /clients/{client_id}/analytics/apps/{app_id}/utilization

Returns aggregate utilization metrics for one specific app over a requested period. This is the app-detail companion to App Utilization: same metric family, same comparison semantics, but scoped to a single app.

Use this endpoint for period-level cards and summary values on an app detail page. For daily charts, use App Activity. For the per-user breakdown within the same app, use App Utilization Users for One App.

Data source is app_usage_reports, aggregated across all dates in the requested period rather than grouped by day.

Use Case

Use this endpoint to:

Render the summary metrics for an app detail view
Show total unique users for one app over a period
Show period-over-period changes for one app's usage
Keep the app detail cards aligned with the formulas used by App Utilization

Path Parameters

Parameter	Type	Description
`client_id`	string (uuid)	Unique identifier for the client organization
`app_id`	string (uuid)	Unique identifier for the application

Query Parameters

Parameter	Type	Required	Default	Description
`granularity`	string	Yes	-	Aggregation granularity: `daily`, `weekly`, `monthly`, `quarterly`. Determines how `avg_time_ms_per_day` is computed.
`start_date`	string	Yes	-	Start of period (YYYY-MM-DD)
`end_date`	string	Yes	-	End of period, inclusive (YYYY-MM-DD)
`compare_start_date`	string	No	-	Comparison period start (YYYY-MM-DD). Must be provided with `compare_end_date`.
`compare_end_date`	string	No	-	Comparison period end, inclusive (YYYY-MM-DD). Must be provided with `compare_start_date`.
`department_ids`	string	No	-	Comma-separated department UUIDs to scope usage data to

The singular form department_id is accepted as a deprecated alias. Use the plural form for new integrations. See Filter Parameters: Plural IDs.

Granularity

granularity is required. It controls how avg_time_ms_per_day is computed. It does not affect unique_users, active_time_ms, or session_count, which are always period totals. See Analytics Pattern: Granularity.

Comparison period

When both compare_start_date and compare_end_date are provided, the change_pct field inside each metric object contains the percentage change from the comparison period to the primary period. When omitted, all change_pct fields are null.

Providing only one of the two comparison parameters returns 400.

Response

Returns an AppUtilizationDetail object.

Example Requests

Monthly utilization detail for one app

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/apps/f1a2b3c4-d5e6-7890-abcd-ef1234567890/utilization?granularity=monthly&start_date=2026-02-01&end_date=2026-02-28" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

With month-over-month comparison

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/apps/f1a2b3c4-d5e6-7890-abcd-ef1234567890/utilization?granularity=monthly&start_date=2026-02-01&end_date=2026-02-28&compare_start_date=2026-01-01&compare_end_date=2026-01-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Scoped to a department

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/apps/f1a2b3c4-d5e6-7890-abcd-ef1234567890/utilization?granularity=monthly&start_date=2026-02-01&end_date=2026-02-28&department_ids=d1a2b3c4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Responses

With comparison period

{
  "period": {
    "start_date": "2026-02-01",
    "end_date": "2026-02-28",
    "compare_start_date": "2026-01-01",
    "compare_end_date": "2026-01-31"
  },
  "unique_users": { "value": 42, "change_pct": 5.2, "compare_value": 40 },
  "active_time_ms": { "value": 432000000, "change_pct": -3.1, "compare_value": 446000000 },
  "avg_time_ms_per_day": { "value": 15428571, "change_pct": -3.1, "compare_value": 15928571 },
  "session_count": { "value": 1284, "change_pct": 7.8, "compare_value": 1191 }
}

Without comparison period

{
  "period": {
    "start_date": "2026-02-01",
    "end_date": "2026-02-28",
    "compare_start_date": null,
    "compare_end_date": null
  },
  "unique_users": { "value": 42, "change_pct": null, "compare_value": null },
  "active_time_ms": { "value": 432000000, "change_pct": null, "compare_value": null },
  "avg_time_ms_per_day": { "value": 15428571, "change_pct": null, "compare_value": null },
  "session_count": { "value": 1284, "change_pct": null, "compare_value": null }
}