Reference Turnkey Applications Tutorials Visual Designer
Reference Turnkey Applications Tutorials Visual Designer
    • REST API
      • Overview
      • API Endpoint
      • Authentication
      • Requests
      • Responses
      • Paging
      • Reason Codes Dictionary
    • Management APIs
      • Accounts
      • Identity Access Management BETA
        • Identity Access Management Overview
        • Identity Access Management API
          • User Management
            • Create a User
            • Update a User
            • Retrieve a User
            • Delete a User
          • API Keys Management
            • Create an API Key
            • Update an API Key
            • Retrieve an API Key
            • Delete an API Key
      • Applications
      • Clients
        • Create a Client
        • Delete a Client
        • Change Client’s Password
        • Get a List of Available Clients
      • Incoming Phone Numbers
        • IncomingPhoneNumber Instance Resource
        • IncomingPhoneNumbers List Resource
        • Local IncomingPhoneNumber Factory Resource
        • Toll-Free IncomingPhoneNumber Factory Resource
        • Mobile IncomingPhoneNumber Factory Resource
        • Attach a phone number to an application
        • Enable Incoming MMS for an Application
        • Delete a phone number
        • List of Phone Numbers
        • Incoming Phone Number Regex Support
      • Notifications
      • Usage Records
      • Trace Records
    • Voice
      • Calls
        • Call List Resource URI
        • Making a Call
        • Modifying Live Calls
        • Examples
        • List Filter
        • Paging Information
      • Conference Management
        • Supported Operations
        • Conference List Resource URI
      • Conference Participants Management
        • Participants List Resource URI
      • Gather DTMF
      • Gather Speech
      • Say
      • Play
      • Hold
      • Recordings
      • Refers
        • Resource Properties
        • Supported Operations
        • Paging Information
      • Resume
      • SIP Refer Support
    • Messages API - BETA
      • Overview
      • Channel Identities
      • Send Message
      • Status Callback Parameters
      • Status Callback Events
      • Receive Message
        • Incoming Message Request Parameters
      • Get Message List
      • Get Single Message
      • Message Attributes
      • Status Description
    • SMS
      • Messages
        • Send SMS
        • Get SMS List
        • Get single SMS Information
        • SMS Attributes
      • Error Codes
    • Email
    • RCML
      • Overview
        • Interacting with Your Application
        • RCML Verbs
      • Dial
        • Client
        • Conference
        • Number
        • SIP
      • Email
      • Gather
      • Say
      • Play
      • SMS
      • Message - Beta
      • Hold
      • Resume
      • Hangup
      • Pause
      • Redirect
      • Record
      • Reject
      • Refer
    • Visual Designer API
      • List Application Templates
      • :List a Specific Application Template
      • Create a Visual Designer Application
      • Get Application Details
      • Save Application Changes
      • Create Application Parameters
      • List Application Parameters
      • Delete Application Parameters
      • Upload Application Media Files
      • List Application Media Files
      • Play Application Media Files
      • Delete Application Media Files
      • Get Application Logs
      • Delete Application Logs
      • Get Application Settings
      • Modify Application Settings
      • Rename an Application
      • Delete an Application
      • Get Visual Designer Configuration
    • Turnkey Apps APIs
      • Smart 2FA
        • Sending One-Time Passwords
        • Verifying One-Time Passwords
        • Cancel One-Time Passwords
        • Session Detail Record (SDR)
        • Get list of One-Time Passwords
        • Get a Single One-Time Password
        • Usage Record One-Time Passwords
        • Common Response Error Code
        • Limit
          • Create Limit
          • Update Limit
          • Delete Limit
          • Get List of Limits
      • Call Queuing
      • Auto Attendant
        • Users
        • Announcement
        • Auto Attendant System
        • Menu
        • Schedule
        • Phone Number
        • Usage Records
        • Third Party Integration
      • Number Masking
        • Application
        • Mask Number Pool
        • Context
        • Participants
        • Interactions
        • Usage Records
      • Task Router
docs 1.0
  • docs
    • 1.0
  • docs
  • Enterprise:Management APIs
  • Enterprise:Usage Records

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 URI

/2012-04-24/Accounts/{AccountSid}/Usage/Records

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 Count, but may be different for certain usage categories like calls, where Count represents the number of calls and Usage represents the number of minutes.

UsageUnit

The units in which Usage is measured. For example minutes for calls, messages for SMS.

Count

The number of usage events (e.g. the number of calls).

CountUnit

The units in which Count is measured. For example calls for calls, messages for SMS.

Uri

The URI that returns only this UsageRecord, relative to https://Restcomm_IP_ADDRESS

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. Count is the number of calls and Usage is the number of minutes.

SMS

All SMS messages. Count and Usage are both the number of messages sent.

PHONENUMBERS

All phone numbers owned by the account.

RECORDINGS

Recordings of voice calls. Count is the number of recordings and Usage is the number of recorded minutes.

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, StartDate=-30days will make StartDate be 30 days before today.

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, EndDate=+30days will make EndDate be 30 days from today.

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. Count is the number of calls and Usage is the number of minutes.

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. Count and Usage are both the number of messages sent.

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. Count is the number of recordings and Usage is the number of recorded minutes.

RECORDINGSTORAGE

Amount of storage used by call recordings stored for the account. Count is the number of stored recordings, Usage is the number of stored recorded minutes.

UsageRecords Instance Resource

You cannot make requests directly to a UsageRecord resource. Instead, make a request to the UsageRecords list resource or one of its

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'
const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Usage/Records/Daily.json',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);
from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Usage/Records/Daily.json',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/Usage/Records/Daily.json");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}
[
  {
    "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"
  }
}
Platform

Programmable Voice

Programmable SMS

Turnkey Applications

Smart 2FA

Call Queue

Auto Attendant

Number Masking

Task Router

Campaign Manager

Learn

Terms And Conditions

About

ABOUT

CONTACT US

© 2020, All rights reserved.