AI By Department

GET /clients/{client_id}/analytics/apps/ai/departments

Deprecated — Use App Utilization Departments

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

Replacement:

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

Field mapping:

This endpoint	Replacement	Notes
department (DepartmentRef)	department (DepartmentRef)	Identical
user_count	user_count	Identical
approved_user_count	—	Not needed by current UI
unapproved_user_count	—	Not needed by current UI

The Departments tab in the App Usage Dashboard shows user count and app count per department — no approval breakdown. The generic endpoint provides both fields. The approved_user_count / unapproved_user_count split on this endpoint is not displayed in the UI.

Returns a paginated list of departments with AI app usage metrics for the requested period. Each row contains a department reference alongside user counts (total, approved, unapproved) and an optional comparison-period change percentage.

This endpoint powers the AI By Department table. For the summary card metric, use AI By Department Summary.

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.
sort_by	string	No	user_count	Sort field: name, user_count
sort_order	string	No	desc	Sort direction: asc, desc
page_size	integer	No	50	Items per page. Max: 200
cursor	string	No	-	Pagination cursor from a previous response

Comparison period

When both compare_start_date and compare_end_date are provided, user_count.change_pct contains the percentage change from the comparison period to the primary period. When omitted, user_count.change_pct is null.

Providing only one of the two comparison parameters returns 400.

Response

Field	Type	Description
data	AiAppDepartmentItem[]	Array of department usage objects
total_count	integer	Total number of departments with AI app usage matching the current filters
next_cursor	string | null	Cursor for the next page. null when on the last page.

Example Requests

Basic list for February 2026

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/apps/ai/departments?start_date=2026-02-01&end_date=2026-02-28" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

With comparison, sorted by department name

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/apps/ai/departments?start_date=2026-02-01&end_date=2026-02-28&compare_start_date=2026-01-01&compare_end_date=2026-01-31&sort_by=name&sort_order=asc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Responses

With comparison period

{
  "data": [
    {
      "department": {
        "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
        "name": "Sales",
        "description": "Revenue and business development"
      },
      "user_count": { "value": 52, "change_pct": 32.0, "compare_value": 39 },
      "approved_user_count": 31,
      "unapproved_user_count": 1
    },
    {
      "department": {
        "id": "e2b3c4d5-f6a7-8901-bcde-f12345678901",
        "name": "Engineering",
        "description": "Software development and infrastructure teams"
      },
      "user_count": { "value": 40, "change_pct": 11.0, "compare_value": 36 },
      "approved_user_count": 31,
      "unapproved_user_count": 1
    },
    {
      "department": {
        "id": "f3c4d5e6-a7b8-9012-cdef-123456789012",
        "name": "Operations",
        "description": null
      },
      "user_count": { "value": 35, "change_pct": -8.0, "compare_value": 38 },
      "approved_user_count": 31,
      "unapproved_user_count": 1
    },
    {
      "department": {
        "id": "a4d5e6f7-b8c9-0123-defa-234567890123",
        "name": "HR",
        "description": "Human resources and people operations"
      },
      "user_count": { "value": 28, "change_pct": null, "compare_value": null },
      "approved_user_count": 28,
      "unapproved_user_count": 0
    }
  ],
  "total_count": 4,
  "next_cursor": null
}

Without comparison period

{
  "data": [
    {
      "department": {
        "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
        "name": "Sales",
        "description": "Revenue and business development"
      },
      "user_count": { "value": 52, "change_pct": null, "compare_value": null },
      "approved_user_count": 31,
      "unapproved_user_count": 1
    }
  ],
  "total_count": 4,
  "next_cursor": "eyJsYXN0X2lkIjoiZDFhMmIzYzQifQ"
}

Empty Result

{
  "data": [],
  "total_count": 0,
  "next_cursor": null
}

AiAppDepartmentItem

Per-department AI app usage metrics for the requested period.

{
  "department": {
    "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
    "name": "Sales",
    "description": "Revenue and business development"
  },
  "user_count": { "value": 52, "change_pct": 32.0, "compare_value": 39 },
  "approved_user_count": 31,
  "unapproved_user_count": 1
}

Field	Type	Nullable	Description
department	DepartmentRef	No	Department identity reference
user_count	MetricWithDeltaDto	No	Total distinct AI app users in this department during the period
approved_user_count	integer	No	Users in this department using approved AI apps
unapproved_user_count	integer	No	Users in this department using unapproved AI apps

approved_user_count + unapproved_user_count may exceed user_count.value if some users use both approved and unapproved AI apps.

DB source:

DTO Field	DB Aggregation
department	Joined via user-department assignments
user_count.value	COUNT(DISTINCT user_id) from app_usage_reports for AI apps, grouped by department
user_count.change_pct	((current - comparison) / comparison) * 100
user_count.compare_value	The same aggregation as user_count.value applied to the comparison date range. null when no comparison period is requested.
approved_user_count	COUNT(DISTINCT user_id) where apps.is_approved = true, grouped by department
unapproved_user_count	COUNT(DISTINCT user_id) where apps.is_approved = false, grouped by department

Pagination

This endpoint uses cursor-based pagination.

1. Omit cursor on the first request
2. If next_cursor is not null, pass its value as cursor on the next request
3. Repeat until next_cursor is null

Error Responses

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

Notes

• A user is counted under a department if they are assigned to that department at query time. Historical department membership changes are not tracked.
• Users assigned to multiple departments are counted once per department.

Related Endpoints

• AI By Department Summary -- Summary card metric for total AI users
• AI App Users -- AI apps ranked by user count
• List Departments -- Department CRUD list
• AI Apps Overview -- Domain overview