# Get location services usage information ### `POST /usage` Returns the number of device location requests used by an account during a specified time period. Primary accounts can also see usage totals for their managed accounts. To see only the usage by the primary account, use the primary `accountName` and set `"usageForAllAccounts": false`. To see only the usage by a managed account, use the managed `accountName`. The `usageForAllAccounts` setting does not matter. To see usage by all accounts, including the total number of transactions, use the primary `accountName` and set `"usageForAllAccounts": true`. ## 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/loc/v1/usage](/docs/premium-apis/device-location/api-endpoints/devices-location-subscriptions/getlocationserviceusage) ## Request Parameters |Parameter Name|Data Type|Description| |-----|-----|-----| | **accountName** *(required)* | string | The numeric name of the account. Must include any leading zeros. | | **startDate** *(required)* | string ($date) | The first date to be included in the report as mm-dd-yyyy. | | **endDate** *(required)* | string ($date) | The last date to be included in the report as mm-dd-yyyy. | | **usageForAllAccounts** *(optional)* | boolean | Set to **false** to only see usage information for the specified account. If the `accountName` is a primary account, set this to **true** to see usage for all managed accounts. | ## Request Body Example Request Body ```json { "accountName": "0000123456-00001", "startDate": "07-01-2024", "endDate": "07-31-2024", "usageForAllAccounts": true } ``` ## Success Responses **Status 200** A success response for a single account shows the susbscription type, the number of transactions allowed in a billing cycle and the number of transactions used between the requested dates. The response for a primary account with `"usageForAllAccounts": true` also includes the number of transactions for each managed account. Example Success Response for a Primary Account with `"usageForAllAccounts": false`: ```json { "accountName": "0000123456-00001", "usageForAllAcounts": false, "skuName": "TS-LOC-COARSE-CellID-Aggr", "transactionsAllowed": "5000", "totalTransactionCount": "350", "PrimaryAccount": { "accountName": "0000123456-00001", "transactionsCount": "125" }, "ManagedAccounts": [] } ``` Example Success Response for a Primary Account with `"usageForAllAccounts": true`: ```json { "accountName": "000012345-00001", "usageForAllAcounts": true, "skuName": "TS-LOC-COARSE-CellID-Aggr", "transactionsAllowed": "5000", "totalTransactionCount": "350", "PrimaryAccount": { "accountName": "0000123456-00001", "transactionsCount": "125" }, "ManagedAccounts": [ { "accountName": "0000123456-00002", "transactionsCount": "100" }, { "accountName": "0000123456-00003", "transactionsCount": "200" }, { "accountName": "0000123456-00004", "transactionsCount": "300" } ] } ``` Example Success Response for a Managed Account: ```json { "accountName": "0000123456-00004", "usageForAllAcounts": false, "skuName": "TS-LOC-COARSE-CellID-Aggr", "transactionsAllowed": "5000", "totalTransactionCount": "200", "PrimaryAccount": {}, "ManagedAccounts": [ { "accountName": "0000123456-00004", "transactionsCount": "200" } ] } ``` ## Success Parameters |Parameter Name|Data Type|Description| |-----|-----|-----| | **accountName** | string | The billing account for which usage information was requested. | | **usageForAllAccounts** | boolean | Indicates whether the request was for an aggregated usage report (**true**) or non-aggregated (**false**). | | **skuName** | string | The Device Location subscription type, which will be one of these values: **TS-LOC-COARSE-CellID-5K** - Monthly recurring subscription for 5,000 non-GPS device locate requests, **TS-LOC-COARSE-CellID-10K** - Monthly recurring subscription for 10,000 non-GPS device locate requests, **TS-LOC-COARSE-CellID-100K** - Monthly recurring subscription for 100,000 non-GPS device locate requests, **TS-LOC-COARSE-CellID-1M** - Monthly recurring subscription for 1,000,000 non-GPS device locate requests, **TS-LOC-COARSE-CellID-Aggr** or **TS-LOC-COARSE-CellID-Aggr-ECPD** - Aggregated billing account subscription. | | **transactionsAllowed** | string | The number of location requests included with the subscription type. | | **totalTransactionCount** | string | The total number of billable device location requests during the reporting period from all included accounts. | | **primaryAccount** | object | The `accountName` and number of billable device location requests (`transactionsCount`) made by the primary account. | | **transactionsCount** | string | The number of billable device location requests made. | | **ManagedAccounts** | array | Usage for managed accounts. Each object in the array will have its own `accountName` and `transactionsCount`. | ## Failure Responses All error messages are returned in this format: ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ``` Error codes and messages are listed on the [Error Codes page](https://thingspace.verizon.com/documentation/api-documentation.html#/http/device-location/error-codes), along with explanations and suggestions for corrective actions.