Usage Records
Usage Records
The UsageRecords REST resource provides a simple API to retrieve usage made by your Restcomm account during any time period and by any usage category. This makes it easy to build reporting and analytics tools for your application. UsageRecords used in combination with Subaccounts created for each of your end-users make it possible to build recurring usage-based billing systems on top of Restcomm's API with just a few simple API calls.
You can also set up usage triggers to notify your application when a particular category of usage reaches a threshold on a daily, monthly, yearly, or all-time basis. Triggers can help determine if your users have reached a cap on usage, or if your application may have runaway requests. For more on usage triggers, see the Usage Triggers documentation.
UsageRecords List Resource
Resource Properties
This resource and its subresources always return a list of UsageRecords. Each UsageRecord is represented by the following properties:
Property | Description |
---|---|
Category |
The category of usage. See Usage Categories below. |
Description |
A human-readable description of the usage category. |
AccountSid |
The Account that accrued the usage. |
StartDate |
The first date for which usage is included in this UsageRecord, formatted as YYYY-MM-DD. All dates are in GMT. |
EndDate |
The last date for which usage is included in this UsageRecord, formatted as YYYY-MM-DD. All dates are in GMT. |
Usage |
The amount of usage (e.g. the number of call minutes). This is frequently the same as |
UsageUnit |
The units in which |
Count |
The number of usage events (e.g. the number of calls). |
CountUnit |
The units in which |
Uri |
The URI that returns only this UsageRecord, relative to |
SubresourceUris |
Subresource Uris for this UsageRecord. See List Subresources. |
Usage, Count
Each UsageRecord contains three amounts: Usage
, Count
. Usage
is the primary way usage is measured for that category: minutes
for calls, messages
for SMS, etc. Count
is the number of usage events: calls
for calls, etc. Each UsageRecord also has fields that show the units in which each amount is measured: Usage
is measured in units of UsageUnit
, for instance. These fields make it easy to build usage dashboards. For example, you can always display human-readable strings describing usage with "`$Usagz`
Usage Categories
A UsageRecord’s Category
defines the type of usage it represents. The full list of all categories is here, but you’ll usually focus on just a few common categories:
Category | Description |
---|---|
CALLS |
All voice calls. |
SMS |
All SMS messages. |
PHONENUMBERS |
All phone numbers owned by the account. |
RECORDINGS |
Recordings of voice calls. |
HTTP GET
Returns UsageRecords for all usage categories. The list includes paging information.
List Filters
By default, the UsageRecords resource will return one UsageRecord for each Category
, representing all usage accrued all-time for the account. You can filter the usage Category
or change the date-range over which usage is counted using optional GET query parameters. Note that query parameters are case-sensitive:
Parameter | Description |
---|---|
Category |
Only include usage of this usage category. |
StartDate |
Only include usage that has occurred on or after this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, |
EndDate |
Only include usage that has occurred on or before this date. Format is YYYY-MM-DD. All dates are in GMT. As a convenience, you can also specify offsets to today. For example, |
For example, you might request all usage records for the month of April, 2012. In this case, the query string would be StartDate=2012-04-01&EndDate=2012-04-30
. This would return one UsageRecord for each usage-type summarizing the usage during April. The list includes paging information. It’s also possible to group usage by day, by month, or by year using the subresources described below.
List Subresources
The main UsageRecords list resource supports a variety of convenience subresources. In general these take the form:
/2012-04-24/Accounts/\{AccountSid}/Usage/Records/{Subresource}
Supported subresources are:
Subresource | Description |
---|---|
Daily |
Return multiple UsageRecords for each usage category, each representing usage over a daily time-interval. |
Monthly |
Return multiple UsageRecords for each usage category, each representing usage over a monthly time-interval. |
Yearly |
Return multple UsageRecords for each usage category, each representing usage over a yearly time-interval. |
AllTime |
Return a single UsageRecord for each usage category, each representing usage over the date-range specified. This is the same as the root /Usage/Records. |
Today |
Return a single UsageRecord per usage category, for today’s usage only. |
Yesterday |
Return a single UsageRecord per usage category, for yesterday’s usage only. |
ThisMonth |
Return a single UsageRecord per usage category, for this month’s usage only. |
LastMonth |
Return a single UsageRecord per usage category, for last month’s usage only. |
These convenience subresources can be used to draw a graph of daily calls, display dashboards of monthly usage across all usage categories, or build a simple usage-based billing system based on last month’s usage totals. All subresources support the same list filters as the root UsageCounters resource.
HTTP POST
Not supported.
HTTP PUT
Not supported.
HTTP DELETE
Not supported.
Full List of All Usage Categories
The full list of supported usage categories are:
Category | Description |
---|---|
CALLS |
All voice calls, inbound & outbound. |
CALLS-INBOUND |
All inbound voice calls, to both toll-free and local numbers. |
CALLS-INBOUND-LOCAL |
All inbound voice calls to local numbers. |
CALLS-INBOUND-TOLLFREE |
All inbound voice calls to toll-free numbers. |
CALLS-OUTBOUND |
All outbound voice calls. |
CALLS-CLIENT |
All Restcomm Client voice calls. |
CALLS-SIP |
All SIP calls. |
SMS |
All SMS messages, both inbound and outbound. |
SMS-INBOUND |
All inbound SMS messages, to both short-codes and long-codes. |
SMS-INBOUND-SHORTCODE |
All inbound SMS messages to short-codes. |
SMS-INBOUND-LONGCODE |
All inbound SMS messages to long-codes. |
SMS-OUTBOUND |
All outbound SMS messages, from both short-codes and long-codes. |
SMS-OUTBOUND-SHORTCODE |
All outbound SMS messages from short-codes. |
SMS-OUTBOUND-LONGCODE |
All outbound SMS messages from long-codes. |
PHONENUMBERS |
All phone numbers owned by the account, toll-free and local. |
PHONENUMBERS-TOLLFREE |
All toll-free phone numbers owned by the account. |
PHONENUMBERS-LOCAL |
All local phone numbers owned by the account. |
RECORDINGS |
Recordings of voice calls. |
RECORDINGSTORAGE |
Amount of storage used by call recordings stored for the account. |
Paging
The following paging parameters are supported
Query Parameter |
Description |
Page |
Which page of Profile records to return, starting from 0. |
PageSize |
Number of records returned per page. |
Additional Paging Information
The API returns URIs to the next, previous, first and last pages of the returned list as shown in the table below:
Request Parameters
Parameter | Description |
---|---|
Uri |
The URI of the current page. |
Firstpageuri |
The URI for the first page of this list. |
Nextpageuri |
The URI for the next page of this list. |
Previouspageuri |
The URI for the previous page of this list. |
Lastpageuri |
The URI for the last page of this list. |
NumPages |
The total number of pages. |
Total |
The total number of items in the list. |
Start |
The position in the overall list of the first item in this page. |
End |
The position in the overall list of the last item in this page. |
Example of Getting Daily Calls Stats
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Usage/Records/Daily.json \
-u 'YourAccountSid:YourAuthToken'
[ { "category": "calls", "description": "Total Calls", "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "start_date": "2020-03-09", "end_date": "2020-03-10", "usage": "1", "usage_unit": "minutes", "count": "1", "count_unit": "calls", "uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records/Daily?Category=calls&StartDate=2020-03-09&EndDate=2020-03-10" }, { "category": "calls", "description": "Total Calls", "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "start_date": "2020-03-11", "end_date": "2020-03-12", "usage": "0", "usage_unit": "minutes", "count": "1", "count_unit": "calls", "uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records/Daily?Category=calls&StartDate=2020-03-11&EndDate=2020-03-12" }, { "category": "calls", "description": "Total Calls", "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "start_date": "2020-03-12", "end_date": "2020-03-13", "usage": "1", "usage_unit": "minutes", "count": "3", "count_unit": "calls", "uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records/Daily?Category=calls&StartDate=2020-03-12&EndDate=2020-03-13" } }