AI By Department Summary
GET /clients/{client_id}/analytics/apps/ai/departments/summary
This endpoint is fully redundant. Use 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 endpoint | Replacement | Notes |
|---|---|---|
total_users | users | Identical data — distinct AI app users in the period |
There are no unique fields on this endpoint. The generic replacement is a complete substitute. It also returns additional metrics (apps_used, apps_discovered, apps_dropped_off, categories_used, departments) in the same call.
Returns the total number of distinct AI app users across all departments. Use this endpoint to power the summary card on the AI By Department dashboard.
For the paginated department-level breakdown, use AI By Department.
For what qualifies as an "AI App", see AI Apps Overview.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
client_id | string (uuid) | Unique identifier for the client organization |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
granularity | string | Yes | - | Aggregation granularity: daily, weekly, monthly, quarterly |
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. |
Comparison period
When both compare_start_date and compare_end_date are provided, total_users.change_pct contains the percentage change from the comparison period to the primary period. When omitted, it is null.
Providing only one of the two comparison parameters returns 400.
Response
Returns an AiAppDepartmentsSummary 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/departments/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/departments/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": 58, "change_pct": 11.5, "compare_value": 52 }
}
Without comparison period
{
"total_users": { "value": 58, "change_pct": null, "compare_value": null }
}
AiAppDepartmentsSummary
| Field | Type | Nullable | Description |
|---|---|---|---|
total_users | MetricWithDeltaDto | No | Total distinct AI app users across all departments during the period |
DB source:
| DTO Field | DB Aggregation |
|---|---|
total_users.value | COUNT(DISTINCT user_id) from app_usage_reports for AI apps, joined to user-department assignments |
total_users.change_pct | ((current - comparison) / comparison) * 100 |
total_users.compare_value | The same aggregation as total_users.value applied to the comparison date range. null when no comparison period is requested. |
Error Responses
| Status | Description |
|---|---|
| 400 | Invalid parameters (bad date format, range exceeds 366 days, mismatched comparison params) |
| 401 | Authentication required |
| 403 | Insufficient permissions for this client |
| 404 | Client not found |
| 500 | Server error |
Related Endpoints
- AI By Department -- Paginated department-level breakdown
- AI App Users Summary -- Summary metrics for AI app user adoption
- AI Apps Overview -- Domain overview