App Utilization Export

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

Returns the same filtered and sorted dataset as App Utilization, but as a downloadable CSV instead of paginated JSON.

This is the V2 replacement for GET /internal/v1/clients/{client_id}/saas-utilization/apps/export.

For the shared export design rules, see Export endpoints.

Use Case

Use this endpoint to:

• Export the current SaaS utilization table exactly as filtered in the UI
• Download a spreadsheet-friendly snapshot of app usage metrics for a date range
• Share or archive the current sorted table without replaying pagination in the client

Path Parameters

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

Query Parameters

This endpoint accepts the same filtering and sorting parameters as App Utilization, except pagination parameters are not supported.

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.
filter	string	No	-	Filter by discovery status: discovered, dropped_off
q	string	No	-	Search against canonical_name (case-insensitive, partial match)
category_ids	string	No	-	Comma-separated catalog category UUIDs to filter by
vendor_ids	string	No	-	Comma-separated catalog vendor UUIDs to filter by
is_favorite	boolean	No	-	Filter by favorite status
is_approved	boolean	No	-	Filter by approval status
department_ids	string	No	-	Comma-separated department UUIDs to scope usage data to
sort_by	string	No	canonical_name	Sort field: canonical_name, unique_users, active_time, avg_time, session_count
sort_order	string	No	desc	Sort direction: asc, desc

cursor and page_size are not accepted. The response always contains the full filtered result set.

Response

This endpoint returns a UTF-8 CSV file.

Header	Type	Description
app_id	string	Client-scoped app ID
catalog_app_id	string	Backing catalog app ID
app_name	string	Canonical app name
vendor_name	string	Catalog vendor name
category_names	string	Semicolon-separated category names
is_favorite	boolean	Favorite status
is_approved	boolean	Approval status
license_count	integer	License count from the app record
unique_users	integer	Current-period distinct users
unique_users_change_pct	number	Percent change vs comparison period; blank when no comparison period
unique_users_compare_value	integer	Comparison-period distinct users; blank when no comparison period
active_time_ms	integer	Current-period active time in milliseconds
active_time_change_pct	number	Percent change vs comparison period; blank when no comparison period
active_time_compare_value	integer	Comparison-period active time in milliseconds; blank when no comparison period
avg_time_ms_per_day	integer	Current-period average time per day in milliseconds
avg_time_ms_per_day_change_pct	number	Percent change vs comparison period; blank when no comparison period
avg_time_ms_per_day_compare_value	integer	Comparison-period average time per day in milliseconds; blank when no comparison period
session_count	integer	Current-period session count
session_count_change_pct	number	Percent change vs comparison period; blank when no comparison period
session_count_compare_value	integer	Comparison-period session count; blank when no comparison period
usage_level	string	Usage intensity: heavy, medium, light
risk_level	string	Risk classification: critical, medium, low; blank for approved apps

Headers

Header	Example Value	Description
Content-Type	text/csv; charset=utf-8	CSV payload
Content-Disposition	attachment; filename="app-utilization-2026-02-01-to-2026-02-28.csv"	Download hint

Example Request

curl -L "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/analytics/apps/utilization/export?granularity=monthly&start_date=2026-02-01&end_date=2026-02-28&category_ids=a7b8c9d0-e1f2-3456-abcd-789012345678&sort_by=active_time&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o app-utilization.csv

Example Response Body

app_id,catalog_app_id,app_name,vendor_name,category_names,is_favorite,is_approved,license_count,unique_users,unique_users_change_pct,unique_users_compare_value,active_time_ms,active_time_change_pct,active_time_compare_value,avg_time_ms_per_day,avg_time_ms_per_day_change_pct,avg_time_ms_per_day_compare_value,session_count,session_count_change_pct,session_count_compare_value,usage_level,risk_level
f1a2b3c4-d5e6-7890-abcd-ef1234567890,a1b2c3d4-e5f6-7890-abcd-ef1234567890,Slack,"Salesforce, Inc.",Communication,true,true,50,42,5.2,40,432000000,-3.1,446000000,15428571,-3.1,15928571,1284,7.8,1191,heavy,
g2b3c4d5-e6f7-8901-bcde-f12345678901,b2c3d4e5-f6a7-8901-bcde-f12345678901,GitHub,"GitHub, Inc.","Developer Tools; Engineering",false,true,,28,12,25,216000000,8.4,199440000,7714285,8.4,7116285,892,15.3,774,medium,

Constraints

• Uses the same validation rules as App Utilization for date ranges, comparison symmetry, and filters.
• Row order matches the requested sort_by / sort_order.
• The export is a snapshot of the full filtered dataset at request time. It is not paginated.

Error Responses

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

Related Endpoints

• App Utilization -- Paginated JSON table for the same dataset
• App Utilization Summary -- Aggregate card counts for the same domain