How To Track and Report Your Twilio Usage

One of the common questions we receive from customers is “How can I report on and download my call log activity”? There are a few ways you can go about doing this. One of the great things about Twilio is that we provide an API for querying usage data, so it’s up to you to decide how your application will consume the data. Given that flexibility, you should be able to accommodate any custom reporting format or datastore requirements. That being said, we also provide several out of the box, easy to use reporting functions. Let’s take a closer look at some of the options.

Reporting in your account admin dashboard

The Twilio account admin dashboard is a great source of information about your Twilio account usage. You can view detailed voice analytics and SMS analytics. These reports graph out vital information about your account, such as number of calls completed, minutes used and call durations. The reports are viewable over a variety of date ranges. You can also browse Call logs and SMS logs, which provide access to the complete listing of each and every call made and SMS delivered, including information such as the time the call was placed and who it was from and to. Clicking on an individual log record will give you a detailed view of that call, including the start time, end time, duration and cost, or SMS message body. You can also access the Twilio Debugger from your account admin, which provides important notifications about your account activity.

Report from your local datastore

If your application is backed by a database you may find it convenient to import Twilio call and SMS data into your own system. This gives you the flexibility to construct custom reports or to perform ad hoc queries within your own environment. Start by creating tables (or appending fields to an existing table) to store each of the properties of a Twilio call resource and SMS resource.

Each Twilio call and SMS message is assigned a unique identifier called a Sid when it is created. Your application should store the Sid of each call or SMS it creates or is notified about. The Sid will allow you to query the Twilio REST API for complete details about the call, and also allow you to identify the call while it is in progress . You can find the Sid included in the REST response for newly created call and SMS message. It’s also included with each TwiML request Twilio makes to your application.

When Twilio makes a TwiML request to your application during a call in progress, the current properties of that call are included in the request. You can use these properties to update the entry in your local database for a particular call Sid. However, the properties of a call might change over time, so unless you’re interested in realtime reporting you might consider waiting until notification that the call has completed via StatusCallback to update your local call record.

Voice and SMS StatusCallback requests

StatusCallback is a notification by HTTP request that Twilio provides to your application when a call completes or SMS message is delivered. By capturing this request you can determine when a call ends or a SMS message is sent, and receive information describing the call or SMS outcome.
StatusCallback is turned off by default – if you’re updating your local database you will likely want to enable it by including the StatusCallback parameter in each outgoing REST call, and also by filling a value in the ‘Status Callback URL’ field for both voice and SMS in optional settings of incoming numbers in the account dashboard. Since StatusCallback occurs asynchronously and after a call has completed, this is an opportune time to update properties of your local call record. Your application also has more flexibility at this time to process database updates or compile larger reports without impacting user experience.

Some properties such as Price might not be populated until sometime after the call completes. The Duration field is always up to date, so you can use this to account for price. Or, if you prefer to pull in the actual Price as calculated by Twilio, you will need to make another REST request later on to retrieve the updated data. You might consider creating a scheduled task or cron job that periodically makes REST queries for call entries in your local database which don’t yet have a value for Price. For each Sid in those entries, request call resource from the Twilio API and update your local database record accordingly.

Query data using the Twilio REST API

The Twilio REST API provides complete access to list or query your call and SMS log data. To view all calls, you can retrieve a list of calls. To search for specific records you can apply call list filters to query by parameters such as To, From, Status or a date range. You can also look up a particular call record by requesting its call resource. Likewise, REST calls exist to view the SMS Messages list, query by SMS list filters such as To, From or date sent, or to retrieve a particular SMS Message resource.

The default response format Twilio uses for REST calls is XML. However, we also provide some convenient alternative representations, including JSON or CSV for easy download.

REST Resource List Paging

If lists are long, the REST API returns partial results in a single “page”. You will notice
that each REST response includes paging information such as page (current page), numpages (total number of pages) and pagesize (number of records per page) which describe the status of paging. You an use special list filter parameters such as PageSize and Page to control how many records are returned and what page to view, respectively. You may need to make multiple REST calls to access multiple pages of data to retrieve a complete resultset. If you’re requesting a large number of records, I’d encourage you to use a large PageSize value in order to achieve efficiency by making as few HTTP requests as possible. Also of note is that paging works using a 0 based index, so you can expect to view 0 to numpages-1 worth of data.

REST date range filters

You can filter SMS message lists and call lists by a specific date or a date range. The call list filters provides parameters for ‘StartTime’ and ‘EndTime’ and SMS message list filters includes a ‘DateSent’ parameter. Using the format YYYY-MM-DD you may specify specific days to report on. You can also use inequality, such as StartTime<=YYYY-MM-DD and EndTime>=YYYY-MM-DD to report over a date range. The same is true of SMS messages using DateSent<=YYYY-MM-DD or DateSent>=YYYY-MM-DD.

An advanced REST report example

Let’s say you wanted to run a report to gather all call data over a month’s time. By combining paging and date range filters you can the request the report data from Twilio and save the data as a csv spreadsheet. Let’s take a look at the steps needed to create this report.

  1. Make a REST call to the calls list resource. Specify call list filters StartTime>= YYYY-MM-DD and EndTime<= YYYY-MM-DD to confine results to a specific timeframe. Use a page parameter of 0 to request the first page, and a large PageSize value such as 500. Here’s an example:
    https://api.twilio.com/2010-04-01/Accounts/Acxxx/Calls?PageSize=500&Page=0&StartTime>=2011-04-01&EndTime<=2011-05-01
  2. Retrieve the results of the REST call and parse and store the numpages value from the returned XML
  3. Create a data structure such as an array to hold your report data. Iterate over the 500 records of call data returned by the REST call and add them to your array as comma separated strings.
  4. Repeat the steps above for the rest of the pages of data. Remember paging works using a 0 based index, so you’ll want to loop over pages 1 to numpages-1.
  5. Present your report data in the desired format. In this case, write your report data to a file. Each line of the file should contain the one element of the array.

An example of the above steps implemented in Ruby can be found here. A hosted version which you can use to download your log data is available here.

Your data, Your choice

I hope this post helps you to understand the options you have to access log data and report on your Twilio usage. Your data is always available to you for view in your account admin or for consumption via API. If you have any questions about accessing your Twilio log data reporting, please feel free to drop us a line at help@twilio.com. We’re happy to help.