Skip to main content

AI App Users Summary

GET /clients/{client_id}/analytics/apps/ai/users/summary

Deprecated — Use App Utilization Summary

This endpoint is superseded by the generic App Utilization Summary with ?category_ids=<ai_id>.

Replacement:

GET /clients/{client_id}/analytics/apps/utilization/summary?category_ids=<ai_id>

Field mapping:

This endpointReplacementNotes
total_usersusersSame data
approved_app_count—Not needed by current UI
unapproved_app_count—Not needed by current UI
users_gained—Not needed by current UI
users_lost—Not needed by current UI

The unique fields on this endpoint (users_gained, users_lost, approved_app_count, unapproved_app_count) are not displayed in the App Usage Dashboard. The tab header counts use the generic utilization summary.

Returns aggregate user adoption metrics for AI applications. Use this endpoint to power the summary cards on the AI App Users dashboard -- total users, approved/unapproved app counts, and user churn.

For the paginated table of individual AI apps, use AI App Users.

For what qualifies as an "AI App" and the category filtering logic, see AI Apps Overview.

Path Parameters​

ParameterTypeDescription
client_idstring (uuid)Unique identifier for the client organization

Query Parameters​

ParameterTypeRequiredDefaultDescription
granularitystringYes-Aggregation granularity: daily, weekly, monthly, quarterly
start_datestringYes-Start of period (YYYY-MM-DD)
end_datestringYes-End of period, inclusive (YYYY-MM-DD)
compare_start_datestringNo-Comparison period start (YYYY-MM-DD). Must be provided with compare_end_date.
compare_end_datestringNo-Comparison period end, inclusive (YYYY-MM-DD). Must be provided with compare_start_date.

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 AiAppUsersSummary object.

Example Requests​

Basic summary for February 2026​

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/apps/ai/users/summary?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/ai/users/summary?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"

Example Responses​

With comparison period​

{
  "total_users": { "value": 156, "change_pct": 17.3, "compare_value": 133 },
  "approved_app_count": 3,
  "unapproved_app_count": 0,
  "users_gained": { "value": 40, "change_pct": 33.3, "compare_value": 30 },
  "users_lost": { "value": 67, "change_pct": -4.3, "compare_value": 70 }
}

Without comparison period​

{
  "total_users": { "value": 156, "change_pct": null, "compare_value": null },
  "approved_app_count": 3,
  "unapproved_app_count": 0,
  "users_gained": { "value": 40, "change_pct": null, "compare_value": null },
  "users_lost": { "value": 67, "change_pct": null, "compare_value": null }
}

AiAppUsersSummary​

FieldTypeNullableDescription
total_usersMetricWithDeltaDtoNoTotal distinct users of AI apps during the period
approved_app_countintegerNoNumber of approved AI apps in use during the period
unapproved_app_countintegerNoNumber of unapproved AI apps in use during the period
users_gainedMetricWithDeltaDtoNoUsers who started using AI apps during this period (not present in comparison period)
users_lostMetricWithDeltaDtoNoUsers who stopped using AI apps during this period (present in comparison period but not current)

DB source:

DTO FieldDB Aggregation
total_users.valueCOUNT(DISTINCT user_id) from app_usage_reports for AI apps in the period
approved_app_countCOUNT(DISTINCT application_id) where apps.is_approved = true
unapproved_app_countCOUNT(DISTINCT application_id) where apps.is_approved = false
users_gained.valueUsers in current period's distinct set minus comparison period's distinct set
users_lost.valueUsers in comparison period's distinct set minus current period's distinct set
*.change_pct((current - comparison) / comparison) * 100
*.compare_valueThe same aggregation as *.value applied to the comparison date range. null when no comparison period is requested.

Error Responses​

StatusDescription
400Invalid parameters (bad date format, range exceeds 366 days, mismatched comparison params)
401Authentication required
403Insufficient permissions for this client
404Client not found
500Server error

Example Error Response​

{
  "error": {
    "code": "invalid_parameter",
    "message": "compare_start_date requires compare_end_date to be provided",
    "details": {
      "compare_start_date": "2026-01-01",
      "compare_end_date": null
    }
  }
}