GetDeviceUsageHistory

Returns the network data usage history of a device during a specified time period.

Uses and Requirements

Each response includes a maximum of 500 records. To obtain more records, you can call the API multiple times, adjusting the TimestampFilter each time to start where the previous request finished.

You can get device usage history by including a device identifier, or a label in the request. You must have created a label previously using the SetUsageSegmentationLabelsmethod.

About Data Usage Calculations

The ThingSpace Platform calculates three types of usage data: data usage, SMS usage, and rated usage. For RTR customers, domestic usage and international usage might also be returned. These usage data types originate from the following sources:

The ThingSpace Platform updates data usage estimates in near real time, to within 15 minutes of the end of a device’s last data session. For 4G devices that stay connected for extended periods, usage estimates are updated approximately every 6 hours until the device disconnects.
The Verizon Enterprise Network updates SMS usage data every 24 hours, with SMS usage accumulated as of 48 hours in the past, for a total maximum delay of three days.
A Verizon Data Warehouse feed updates rated data and SMS usage daily, with unbilled, non-roaming usage data that is usually two days in arrears. Roaming data may be updated less frequently.

About Date Ranges

There is no date range limit for the Device Usage Report. However, in accordance with Verizon Data Retention Policy, the records contained in this report are kept for 12 months. Though you may specify any date range, you will not receive results for records that are older than 12 months.

Requests for date ranges that span many months may time out due to the time required to retrieve records for every day in the reporting period. If a request times out, try sending two or more requests for shorter date ranges to get the equivalent data.

Request Parameters

Parameter	Type	Description
Device required	DeviceIdentifier	The device for which you want usage history, specified by device identifier. NOTE: You can use GetDeviceList to get a list of all devices in the account.
Kind required	string	The type of the device identifier. Valid types of identifiers are: ESN (decimal) ICCID (up to 20 digits) IMEI (up to 16 digits) MDN MEID (hexadecimal) MSISDN
Identifier required	string	The value of the device identifier.
TimestampFilter required	InclusiveDateTimeRange	Defines the reporting period to be included in the response. For the first request, set Earliest and Latest to cover the time period for which you want data. Check the IsComplete value in the response. If it's "true" then you have received all of the events that occurred during that time. If IsComplete is "false," send another request with Earliest set to the CreatedAt time of the last returned event plus one millisecond. Continue adjusting the Earliest value and sending requests until IsComplete is "true."
Earliest required	dateTime	The earliest date and time in the range.
Latest required	dateTime	The latest date and time in the range.
Label	LabelIdentifier	Label name and value associated with the device.
Name	varchar(20)	The label name associated with the device. For example, VIN.
Value	varchar(50)	The label value.

Response Parameters

Parameter	Type	Description
Device	DeviceIdentifier	The device for which the usage history was returned.
Kind	string	The type of the device identifier. Valid types of identifiers are: ESN (decimal) ICCID (up to 20 digits) IMEI (up to 16 digits) MDN MEID (hexadecimal) MIN MSISDN
Identifier	string	The value of the device identifier.
UsageHistory	DeviceUsage	List of device usage events, sorted by timestamp, oldest first.
Timestamp	dateTime	The date and time at which the event occurred.
ServicePlan	string	The service plan in effect when the event occurred.
BytesUsed	long	The number of bytes that the device sent or received as a result of this device usage event.
SmsUsed	int	The number of SMS messages that occurred as a result of this device usage event.
Source	string	The source of the device usage information for the device usage event, either "raw" (provided by the AAA service) or "processed" (provided by the carrier feed).
ExtendedAttributes	ExtendedAttributesObj	Any extended attributes for the event, as Key and Value pairs.
Key Value	string int	MoSms The number of SMS messages sent by the device during the reporting period.
Key Value	string int	MtSms The number of SMS messages sent to the device during the reporting period.
Key Value	string int	DomesticUsage Domestic usage in bytes. NOTE: Only returned for RTR customers.
Key Value	string int	InternationalUsage International usage in bytes. NOTE: Only returned for RTR customers.
IsComplete	boolean	Indicates whether all event records have been returned. A maximum of 500 records are returned per call to this API. If IsComplete is "false," send another request with Earliest set to the last Timestamp in this response plus one millisecond. Continue adjusting the Earliest value and sending requests until IsComplete is "true."

Example SOAP Request

Example with EID

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://nphase.com/unifiedwebservice/v2" xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService" xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
        <soapenv:Header>
            <token xmlns="http://nphase.com/unifiedwebservice/v2">1565d718-5138-4f8d-89bf-1ec257406911</token>
        </soapenv:Header>
        <soapenv:Body>
            <v2:GetDeviceUsageHistory>
                
                <v2:Input>
                    
                    <nph:Device>
                        <nph1:Kind>eid</nph1:Kind>
                        <nph1:Identifier>69033023312150620000000314148896</nph1:Identifier>
                    </nph:Device>
                    <nph:TimestampFilter>
                        <nph1:Earliest>2020-11-01</nph1:Earliest>
                        <nph1:Latest>2020-12-01</nph1:Latest>
                    </nph:TimestampFilter>
                    
                    <nph:Label xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                </v2:Input>
            </v2:GetDeviceUsageHistory>
        </soapenv:Body>
    </soapenv:Envelope>

Example using Label(VIN)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://nphase.com/unifiedwebservice/v2" xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService" xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
    <soapenv:Header>
        <token xmlns="http://nphase.com/unifiedwebservice/v2">1565d718-5138-4f8d-89bf-1ec257406911</token>
    </soapenv:Header>
    <soapenv:Body>
        <v2:GetDeviceUsageHistory>
            
            <v2:Input>
                
                <nph:Device xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                <nph:TimestampFilter>
                    <nph1:Earliest>2020-01-01</nph1:Earliest>
                    <nph1:Latest>2020-12-31</nph1:Latest>
                </nph:TimestampFilter>
                
                <nph:Label>
                    <nph1:Name>VIN</nph1:Name>
                    <nph1:Value>1234r4535345312123455</nph1:Value>
                </nph:Label>
            </v2:Input>
        </v2:GetDeviceUsageHistory>
    </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
        <s:Body>
            <GetDeviceUsageHistoryResponse xmlns="http://nphase.com/unifiedwebservice/v2">
                <Output xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
                    <a:Device xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
                        <b:Kind>eid</b:Kind>
                        <b:Identifier>69033023312150620000000314148896</b:Identifier>
                    </a:Device>
                    <a:UsageHistory>
                        <a:DeviceUsage>
                            <a:Timestamp>2020-11-18T00:00:00Z</a:Timestamp>
                            <a:ServicePlan/>
                            <a:BytesUsed>4753376</a:BytesUsed>
                            <a:SmsUsed>0</a:SmsUsed>
                            <a:Source>Raw Usage</a:Source>
                            <a:ExtendedAttributes xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
                                <b:ExtendedAttributesObj>
                                    <b:Key>MoSms</b:Key>
                                    <b:Value>0</b:Value>
                                </b:ExtendedAttributesObj>
                                <b:ExtendedAttributesObj>
                                    <b:Key>MtSms</b:Key>
                                    <b:Value>0</b:Value>
                                </b:ExtendedAttributesObj>
                                <b:ExtendedAttributesObj>
                                  <b:Key>DomesticUsage</b:Key>
                                  <b:Value>4096</b:Value>
                                </b:ExtendedAttributesObj>
                                <b:ExtendedAttributesObj>
                                  <b:Key>InternationalUsage</b:Key>
                                  <b:Value>0</b:Value>
                                </b:ExtendedAttributesObj>
                            </a:ExtendedAttributes>
                        </a:DeviceUsage>
                        <a:DeviceUsage>
                            <a:Timestamp>2020-11-19T00:00:00Z</a:Timestamp>
                            <a:ServicePlan/>
                            <a:BytesUsed>208896</a:BytesUsed>
                            <a:SmsUsed>0</a:SmsUsed>
                            <a:Source>Raw Usage</a:Source>
                            <a:ExtendedAttributes xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
                                <b:ExtendedAttributesObj>
                                    <b:Key>MoSms</b:Key>
                                    <b:Value>0</b:Value>
                                </b:ExtendedAttributesObj>
                                <b:ExtendedAttributesObj>
                                    <b:Key>MtSms</b:Key>
                                    <b:Value>0</b:Value>
                                </b:ExtendedAttributesObj>
                                <b:ExtendedAttributesObj>
                                  <b:Key>DomesticUsage</b:Key>
                                  <b:Value>4096</b:Value>
                                </b:ExtendedAttributesObj>
                                <b:ExtendedAttributesObj>
                                  <b:Key>InternationalUsage</b:Key>
                                  <b:Value>0</b:Value>
                                </b:ExtendedAttributesObj>
                            </a:ExtendedAttributes>
                            </a:ExtendedAttributes>
                        </a:DeviceUsage>
    					<a:DeviceUsage>
                            <a:Timestamp>2020-11-20T00:00:00Z</a:Timestamp>
                            <a:ServicePlan/>
                            <a:BytesUsed>208896</a:BytesUsed>
                            <a:SmsUsed>0</a:SmsUsed>
                            <a:Source>Raw Usage</a:Source>
                            <a:ExtendedAttributes xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
                                <b:ExtendedAttributesObj>
                                    <b:Key>MoSms</b:Key>
                                    <b:Value>0</b:Value>
                                </b:ExtendedAttributesObj>
                                <b:ExtendedAttributesObj>
                                    <b:Key>MtSms</b:Key>
                                    <b:Value>0</b:Value>
                                    <b:ExtendedAttributesObj>
                                      <b:Key>DomesticUsage</b:Key>
                                      <b:Value>4096</b:Value>
                                    </b:ExtendedAttributesObj>
                                    <b:ExtendedAttributesObj>
                                      <b:Key>InternationalUsage</b:Key>
                                      <b:Value>0</b:Value>
                                    </b:ExtendedAttributesObj>
                                </a:ExtendedAttributes>
                                </b:ExtendedAttributesObj>
                            </a:ExtendedAttributes>
                        </a:DeviceUsage>
                    </a:UsageHistory>
                    <a:IsComplete>true</a:IsComplete>
                </Output>
            </GetDeviceUsageHistoryResponse>
        </s:Body>
    </s:Envelope>