The Organization Usage endpoint enables organizations to retrieve their API usage statistics. These usage statistics align with the usage reported on https://dash.genability.com/org/usage. The API gives customers more flexibility to dynamically retrieve usage data for use cases such as monitoring, alarming, and more. All usage data is reported month-to-date. To view daily usage data, one must call this endpoint daily and store the daily values. All values are updated daily at midnight UTC.
The Organization Usage endpoint authenticates using the provided appId and appKey. Users may only view usage statistics for the organization to which they belong. If you are part of multiple organizations, please adjust your appId and appKey accordingly.
Resource URI
GET /rest/v1/orgs/usage
Request Parameters
Along with the standard pagination parameters, searching and sorting parameters, and the required security parameters, the following parameters are available as part of the request.
| Name | Type | Description |
|---|---|---|
| populateAggregateUsage | boolean | Boolean flag to indicate whether to include aggregate usage data in the response. |
| populateChildOrgs | boolean | Boolean flag to determine if usage data for child organizations should be included. |
| populateMasterTariffIds | boolean | Boolean flag to specify whether to include master tariff IDs in the response |
| startYearMonth | dateTime | Date flag to filter usage to a specific range. Consistent with the rest of the Signal API we support ISO 8601date formatting, however only the year and month are applied to the query. Users, thus, have the choice of either passing a complete time stamp (2011-06-23T18:45-0700 / 2011-06-23T18:45) or a simplified year and month (2011-06). If no date range is passed the endpoint will return all available records. |
| endYearMonth | dateTime | Date flag to filter usage to a specific range. Consistent with the rest of the Signal API we support ISO 8601 date formatting, however only the year and month are applied to the query. Users, thus, have the choice of either passing a complete time stamp (2011-06-23T18:45-0700 / 2011-06-23T18:45) or a simplified year and month (2011-06). If no date range is passed the endpoint will return all available records. |
Response Parameters
| Name | Type | Description |
|---|---|---|
| apiCredits | number | Total number of billable API calls made during the usage period. |
| calcCredits | number | Total number of calculation calls made during the usage period. |
| tariffCredits | number | Number of unique tariffs accessed during the usage period. |
| accountsCreated | number | Number of Switch accounts created during the usage period. |
| fullSwitchEnabled | number | Number of Full Switch (more context on Full Switches here) accounts enabled during the usage period. |
| accountsGivenStorage | number | Number of Switch accounts provisioned with Storage profiles during the usage period. |
| completeMonth | boolean | Flag that indicates if the given month's usage data is complete or not. True = complete month, false = incomplete month. |
| activityToDate | dateTime | Timestamp that indicates when the given month's data was last refreshed. |
| storageProfilesCreated | number | Number of Storage profiles created during the usage period. |
| residentialTarfiffsCount | number | Number of unique residential tariffs accessed during the usage period. |
| commercialTariffsCount | number | Number of unique commercial tariffs accessed during the usage period. |
| tariffsCount | number | Equivalent to tariffCredits. Number of unique tariffs accessed during the usage period. |
Example:
GET /rest/v1/orgs/usage?populateChildOrgs=true&populateMasterTariffIds=true
The above asks for the monthly usage data, including break outs for each child organization, and an enumerated list of MTIDs accessed.
{
"status": "success",
"count": 58,
"type": "OrgUsage",
"results": [
{
"orgName": "Genability",
"year": 2024,
"month": 12,
"usage": {
"apiCredits": 30356,
"calcCredits": 13280,
"tariffCredits": 248,
"accountsCreated": 6616,
"fullSwitchEnabled": 604,
"accountsGivenStorage": 43,
"masterTariffIds": [
512,
3424821,
518,
...
],
"completeMonth": false,
"activityToDate": "2024-12-17T00:00:00+00:00",
"storageProfilesCreated": 72,
"tariffBillingUsage": {
"residentialTariffsCount": 45,
"commercialTariffsCount": 203,
"internationalTariffsCount": 0,
"tariffsCount": 248
}
},
"childOrgUsage": [
{
"orgName": "genability-childOrg1",
"year": 2024,
"month": 12,
"usage": {
"apiCredits": 1076,
"calcCredits": 0,
"tariffCredits": 0,
"accountsCreated": 241,
"fullSwitchEnabled": 51,
"accountsGivenStorage": 0,
"completeMonth": false,
"activityToDate": "2024-12-16T00:00:00+00:00",
"storageProfilesCreated": 0
}
}
]
},
{
"orgId": "c0c31669-52bd-489f-9438-f5727b562cdb",
"orgName": "Genability",
"year": 2024,
"month": 11,
"usage": {
"apiCredits": 143306,
"calcCredits": 33792,
"tariffCredits": 847,
"accountsCreated": 16624,
"fullSwitchEnabled": 1511,
"accountsGivenStorage": 288,
"masterTariffIds": [
3487797,
3487796,
3487799,
...
],
"completeMonth": true,
"activityToDate": "2024-12-01T00:00:00+00:00",
"storageProfilesCreated": 479,
"tariffBillingUsage": {
"residentialTariffsCount": 129,
"commercialTariffsCount": 718,
"internationalTariffsCount": 2,
"tariffsCount": 847
}
},
"childOrgUsage": [
{
"orgName": "genability-childOrg1",
"year": 2024,
"month": 11,
"usage": {
"apiCredits": 8651,
"calcCredits": 0,
"tariffCredits": 0,
"accountsCreated": 1879,
"fullSwitchEnabled": 453,
"accountsGivenStorage": 0,
"completeMonth": false,
"activityToDate": "2024-11-29T00:00:00+00:00",
"storageProfilesCreated": 0
}
}
]
},
...