Skip to content

Most visited

Recently visited

navigation

NetworkStatsManager

public class NetworkStatsManager
extends Object

java.lang.Object
   ↳ android.app.usage.NetworkStatsManager


Provides access to network usage history and statistics. Usage data is collected in discrete bins of time called 'Buckets'. See NetworkStats.Bucket for details.

Queries can define a time interval in the form of start and end timestamps (Long.MIN_VALUE and Long.MAX_VALUE can be used to simulate open ended intervals). By default, apps can only obtain data about themselves. See the below note for special cases in which apps can obtain data about other applications.

Summary queries

querySummaryForDevice(int, String, long, long)

querySummaryForUser(int, String, long, long)

querySummary(int, String, long, long)

These queries aggregate network usage across the whole interval. Therefore there will be only one bucket for a particular key, state, metered and roaming combination. In case of the user-wide and device-wide summaries a single bucket containing the totalised network usage is returned.

History queries

queryDetailsForUid(int, String, long, long, int)

queryDetails(int, String, long, long)

These queries do not aggregate over time but do aggregate over state, metered and roaming. Therefore there can be multiple buckets for a particular key but all Bucket's state is going to be STATE_ALL, all Bucket's metered is going to be METERED_ALL, and all Bucket's roaming is going to be ROAMING_ALL.

NOTE: Calling querySummaryForDevice(int, String, long, long) or accessing stats for apps other than the calling app requires the permission PACKAGE_USAGE_STATS, which is a system-level permission and will not be granted to third-party apps. However, declaring the permission implies intention to use the API and the user of the device can grant permission through the Settings application.

Profile owner apps are automatically granted permission to query data on the profile they manage (that is, for any query except querySummaryForDevice(int, String, long, long)). Device owner apps and carrier- privileged apps likewise get access to usage data for all users on the device.

In addition to tethering usage, usage by removed users and apps, and usage by the system is also included in the results for callers with one of these higher levels of access.

NOTE: Prior to API level Build.VERSION_CODES.N, all calls to these APIs required the above permission, even to access an app's own data usage, and carrier-privileged apps were not included.

Instances of this class must be obtained using Context.getSystemService(Class) with the argument NetworkStatsManager.class or Context.getSystemService(String) with the argument Context.NETWORK_STATS_SERVICE.

Summary

Nested classes

class NetworkStatsManager.UsageCallback

Base class for usage callbacks. 

Public methods

NetworkStats queryDetails(int networkType, String subscriberId, long startTime, long endTime)

Query network usage statistics details.

NetworkStats queryDetailsForUid(int networkType, String subscriberId, long startTime, long endTime, int uid)

Query network usage statistics details for a given uid.

NetworkStats queryDetailsForUidTag(int networkType, String subscriberId, long startTime, long endTime, int uid, int tag)

Query network usage statistics details for a given uid and tag.

NetworkStats querySummary(int networkType, String subscriberId, long startTime, long endTime)

Query network usage statistics summaries.

NetworkStats.Bucket querySummaryForDevice(int networkType, String subscriberId, long startTime, long endTime)

Query network usage statistics summaries.

NetworkStats.Bucket querySummaryForUser(int networkType, String subscriberId, long startTime, long endTime)

Query network usage statistics summaries.

void registerUsageCallback(int networkType, String subscriberId, long thresholdBytes, NetworkStatsManager.UsageCallback callback, Handler handler)

Registers to receive notifications about data usage on specified networks.

void registerUsageCallback(int networkType, String subscriberId, long thresholdBytes, NetworkStatsManager.UsageCallback callback)

Registers to receive notifications about data usage on specified networks.

void unregisterUsageCallback(NetworkStatsManager.UsageCallback callback)

Unregisters callbacks on data usage.

Inherited methods

From class java.lang.Object

Public methods

queryDetails

added in API level 23
NetworkStats queryDetails (int networkType, 
                String subscriberId, 
                long startTime, 
                long endTime)

Query network usage statistics details. Result filtered to include only uids belonging to calling user. Result is aggregated over state but not aggregated over time, uid, tag, metered, nor roaming. This means buckets' start and end timestamps are going to be between 'startTime' and 'endTime' parameters. State is going to be STATE_ALL, uid will vary, tag TAG_NONE, metered is going to be METERED_ALL, and roaming is going to be ROAMING_ALL.

Only includes buckets that atomically occur in the inclusive time range. Doesn't interpolate across partial buckets. Since bucket length is in the order of hours, this method cannot be used to measure data usage on a fine grained time scale.

Parameters
networkType int: As defined in ConnectivityManager, e.g. TYPE_MOBILE, TYPE_WIFI etc.

subscriberId String: If applicable, the subscriber id of the network interface.

startTime long: Start of period. Defined in terms of "Unix time", see currentTimeMillis().

endTime long: End of period. Defined in terms of "Unix time", see currentTimeMillis().

Returns
NetworkStats Statistics object or null if permissions are insufficient or error happened during statistics collection.

Throws
SecurityException
RemoteException

queryDetailsForUid

added in API level 23
NetworkStats queryDetailsForUid (int networkType, 
                String subscriberId, 
                long startTime, 
                long endTime, 
                int uid)

Query network usage statistics details for a given uid. #see queryDetailsForUidTag(int, String, long, long, int, int)

Parameters
networkType int

subscriberId String

startTime long

endTime long

uid int

Returns
NetworkStats

Throws
SecurityException
RemoteException

queryDetailsForUidTag

added in API level 24
NetworkStats queryDetailsForUidTag (int networkType, 
                String subscriberId, 
                long startTime, 
                long endTime, 
                int uid, 
                int tag)

Query network usage statistics details for a given uid and tag. Only usable for uids belonging to calling user. Result is aggregated over state but not aggregated over time. This means buckets' start and end timestamps are going to be between 'startTime' and 'endTime' parameters. State is going to be STATE_ALL, uid the same as the 'uid' parameter and tag the same as 'tag' parameter. metered is going to be METERED_ALL, and roaming is going to be ROAMING_ALL.

Only includes buckets that atomically occur in the inclusive time range. Doesn't interpolate across partial buckets. Since bucket length is in the order of hours, this method cannot be used to measure data usage on a fine grained time scale.

Parameters
networkType int: As defined in ConnectivityManager, e.g. TYPE_MOBILE, TYPE_WIFI etc.

subscriberId String: If applicable, the subscriber id of the network interface.

startTime long: Start of period. Defined in terms of "Unix time", see currentTimeMillis().

endTime long: End of period. Defined in terms of "Unix time", see currentTimeMillis().

uid int: UID of app

tag int: TAG of interest. Use TAG_NONE for no tags.

Returns
NetworkStats Statistics object or null if an error happened during statistics collection.

Throws
SecurityException if permissions are insufficient to read network statistics.

querySummary

added in API level 23
NetworkStats querySummary (int networkType, 
                String subscriberId, 
                long startTime, 
                long endTime)

Query network usage statistics summaries. Result filtered to include only uids belonging to calling user. Result is aggregated over time, hence all buckets will have the same start and end timestamps. Not aggregated over state, uid, metered, or roaming. This means buckets' start and end timestamps are going to be the same as the 'startTime' and 'endTime' parameters. State, uid, metered, and roaming are going to vary, and tag is going to be the same.

Parameters
networkType int: As defined in ConnectivityManager, e.g. TYPE_MOBILE, TYPE_WIFI etc.

subscriberId String: If applicable, the subscriber id of the network interface.

startTime long: Start of period. Defined in terms of "Unix time", see currentTimeMillis().

endTime long: End of period. Defined in terms of "Unix time", see currentTimeMillis().

Returns
NetworkStats Statistics object or null if permissions are insufficient or error happened during statistics collection.

Throws
SecurityException
RemoteException

querySummaryForDevice

added in API level 23
NetworkStats.Bucket querySummaryForDevice (int networkType, 
                String subscriberId, 
                long startTime, 
                long endTime)

Query network usage statistics summaries. Result is summarised data usage for the whole device. Result is a single Bucket aggregated over time, state, uid, tag, metered, and roaming. This means the bucket's start and end timestamp are going to be the same as the 'startTime' and 'endTime' parameters. State is going to be STATE_ALL, uid UID_ALL, tag TAG_NONE, metered METERED_ALL, and roaming ROAMING_ALL.

Parameters
networkType int: As defined in ConnectivityManager, e.g. TYPE_MOBILE, TYPE_WIFI etc.

subscriberId String: If applicable, the subscriber id of the network interface.

startTime long: Start of period. Defined in terms of "Unix time", see currentTimeMillis().

endTime long: End of period. Defined in terms of "Unix time", see currentTimeMillis().

Returns
NetworkStats.Bucket Bucket object or null if permissions are insufficient or error happened during statistics collection.

Throws
SecurityException
RemoteException

querySummaryForUser

added in API level 23
NetworkStats.Bucket querySummaryForUser (int networkType, 
                String subscriberId, 
                long startTime, 
                long endTime)

Query network usage statistics summaries. Result is summarised data usage for all uids belonging to calling user. Result is a single Bucket aggregated over time, state and uid. This means the bucket's start and end timestamp are going to be the same as the 'startTime' and 'endTime' parameters. State is going to be STATE_ALL, uid UID_ALL, tag TAG_NONE, metered METERED_ALL, and roaming ROAMING_ALL.

Parameters
networkType int: As defined in ConnectivityManager, e.g. TYPE_MOBILE, TYPE_WIFI etc.

subscriberId String: If applicable, the subscriber id of the network interface.

startTime long: Start of period. Defined in terms of "Unix time", see currentTimeMillis().

endTime long: End of period. Defined in terms of "Unix time", see currentTimeMillis().

Returns
NetworkStats.Bucket Bucket object or null if permissions are insufficient or error happened during statistics collection.

Throws
SecurityException
RemoteException

registerUsageCallback

added in API level 24
void registerUsageCallback (int networkType, 
                String subscriberId, 
                long thresholdBytes, 
                NetworkStatsManager.UsageCallback callback, 
                Handler handler)

Registers to receive notifications about data usage on specified networks.

The callbacks will continue to be called as long as the process is live or unregisterUsageCallback(NetworkStatsManager.UsageCallback) is called.

Parameters
networkType int: Type of network to monitor. Either TYPE_MOBILE or TYPE_WIFI.

subscriberId String: If applicable, the subscriber id of the network interface.

thresholdBytes long: Threshold in bytes to be notified on.

callback NetworkStatsManager.UsageCallback: The NetworkStatsManager.UsageCallback that the system will call when data usage has exceeded the specified threshold.

handler Handler: to dispatch callback events through, otherwise if null it uses the calling thread.

registerUsageCallback

added in API level 24
void registerUsageCallback (int networkType, 
                String subscriberId, 
                long thresholdBytes, 
                NetworkStatsManager.UsageCallback callback)

Registers to receive notifications about data usage on specified networks. #see registerUsageCallback(int, String[], long, UsageCallback, Handler)

Parameters
networkType int

subscriberId String

thresholdBytes long

callback NetworkStatsManager.UsageCallback

unregisterUsageCallback

added in API level 24
void unregisterUsageCallback (NetworkStatsManager.UsageCallback callback)

Unregisters callbacks on data usage.

Parameters
callback NetworkStatsManager.UsageCallback: The NetworkStatsManager.UsageCallback used when registering.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)