# Retrieve Device Aggregate Usage ### `POST /v1/devices/usage/actions/promoaggregateusage` Retrives the aggregate data usage for all the MDNless devices during the promotional period. ## Header Parameters The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit [Getting Started](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/getting-started). | Parameter Name | Data Type | Description | | :------------------------------ | :--------- | :---------------------------------------------------------------- | | **Authorization** *(required)* | string | HTTP Authorization bearer token: `Authorization: Bearer {token}` | | **VZ-M2M-Token** *(required)* | string | A valid session token: `VZ-M2M-Token: {M2Mtoken}` | | **Content-Type** *(required)* | string | Must be application/json `Content-Type: application/json` | ## HTTP Request [POST https://thingspace.verizon.com/api/m2m/v1/devices/usage/actions/promoaggregateusage](/docs/standard-apis/ready-sim/api-endpoints/promotion-period-information/retrieve-aggregate-usage/getpromodeviceaggregateusagehistory) ## Request Parameters | Parameter Name | Data Type | Description | |:----------------|:-----------|:-------------| | accountName *(required)* | string | The name of a billing account. An account name is usually numeric and must include any leading zeros. | | deviceId *(required)* | array | an array of the kind of device identifier and what the value of that identifier is. | | deviceId.kind | string | The type of device identifier. This will be the identifier of the SIM card or ICCID (Integrated Circuit Card ID) | | deviceId.value | string | The 20-digit ICCID. | | startTime | string (date-time) | The starting time of the query period. | | endTime | string(date-time) | The ending time of the query period. | ## Request Body The request body identifies the account that Anomaly Detection willl be activated for and sets initial maximums for abnormal and very abnormal and if abnormal, very abnormal or both will be monitored. Example Request Body: ```json { "accountName": "0000123456-00001", "deviceIds": [ { "kind": "iccid", "id": "20-digit ICCID" } ], "startTime": "2021-08-15T00:00:00Z", "endTime": "2021-08-16T00:00:00Z" } ``` ## Success Responses A successful request will return a request ID to identify the request in a callback. To learn more about callbacks, please visit [About Callback Services](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services). **Status 200** Example Success Response: ```json { "requestId": "595f5c44-c31c-4552-8670-020a1545a84d", } ``` ## Failure Responses **Status 400** All failure responses are in this format: ```json { "errorCode": "error code string", "errorMessage": "error message string" } ``` Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions. ## Callback Response To learn more about callbacks, please visit [About Callback Services](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/working-with-verizon-wireless/about-callback-services). There will be two callbacks received: **Example callback with a comment stating "request completed processing":** ```json { "username": "null", "password": "null", "requestId": "595f5c44-c31c-4552-8670-020a1545a84d", "deviceResponse": {}, "comment": "Request Completed Processing", "callbackCount": 1, "maxCallbackThreshold": 4 } ``` **Example callback with usage data:** ```json { "username": "null", "password": "null", "requestId": "595f5c44-c31c-4552-8670-020a1545a84d", "deviceResponse": { "devicePromoUsageResponse": [ { "deviceIdentifierCollection": [ { "id": "20-digit ICCID", "kind": "ICCID" } ], "dataUsage": "3072", "smsUsage": "0", "moSms": "0", "mtSms": "0", "startDate": "2021-08-15T00:00:00.0000000", "endDate": "2021-08-16T00:00:00.0000000" } ] }, "callbackCount": 1, "maxCallbackThreshold": 4 } ```