Vonage Reports API

Introducing the Vonage Reports API

Published October 14, 2020 by Martyn Davies

The Vonage Reports API is a robust API that allows you to gather data about all of the activity that takes place across your account.

In this post, we’ll look at what data can be exported, how you can access it with both JavaScript and Python, and what using an API like this helps you understand.

Reports API Overview

The Reports API is an API that gives you access to all the underlying data that your usage of our other APIs produces. For example, when you send an SMS from your account, that action is recorded, alongside the following:

  • The cost of sending the message
  • The delivery status
  • The country the recipient is in
  • The recipient’s network provider
  • The body of the message itself
  • How long the message took to deliver

And that’s just some of it! It’s a very detailed API that gives you full control over how much information is included in the generated reports.

Which Products Can You Get Reports For?

The Reports API covers SMS, Voice, Verify, Number Insight, Messages, Conversations, and Automated Speech Recognition usage.

Additionally, you can choose to have your reports show inbound or outbound usage—that’s the difference between receiving a voice call (inbound) and making a voice call (outbound).

Requesting Data Via the Reports API

There are two different types of requests you can make with the Reports API:

  • Synchronous: Optimised for frequent and periodic retrieval of smaller batches of data of up to approximately 10,000 records.
  • Asynchronous: Optimised for infrequent, large queries returning tens of millions of records.

Synchronous vs. Asynchronous

One way to decide which method to use is by looking at how often you want to gather data.

If you need an up to date or on-demand view of your data and you’ll be requesting every hour or every day, the synchronous request method would be adequate.

Alternatively, suppose you’re looking to gather data less frequently, but you know you’ll be generating lots of records over a single month of usage. In that case, the asynchronous request method is the better choice.

On average, the asynchronous request method takes around 5-10 minutes to generate and return 1 million records.

Get a Synchronous Report

We’ll start by making a synchronous request for SMS data over 24 hours using standard libraries for Node.js and Python. You don’t need anything special for these requests so you can adapt them to use your HTTP library of choice.

Node.js Synchronous Request

Request up to 24 hours’ data using Node.js:

Python Synchronous Request

Request up to 24 hours’ data using Python:

Request Asynchronous Report Data

Next, we’ll make the same request for SMS data, but this time we’re expecting it to return up to 10 million records, so we’ll switch to the asynchronous request method for this part. The way this process works is something like:

  • Make a request for asynchronous report data, supplying a callback_url for notification of the report being ready. Then note the request_id received in the response.
  • (optional) Check on the status of the requested report, using the request_id. Once complete, a report with the status SUCCESS will also have the report download_url in the _links section.
  • Receive an HTTP request at the callback_url. This contains the section _links which has the download_url for the report.
  • Download the report from the download_url.

Node.js Asynchronous Request

Make a request for an asynchronous report to be generated, using Node.js:

Python Asynchronous Request

Make a request for an asynchronous report to be generated, using Python:

Checking the Status of Your Reports

You can check on the status of your reports at any time to check if they have completed (in which case the download will be available) or are still in a PENDING state.

Check Report Status with Node.js

Get a status update on an asychronous report with Node.js:

Check Report Status with Python

Get a status update on an asynchronous report with Node.js:

For both of the above examples, the response will look something like this:

Note the download_report URL specified in the response. That URL is a link to the downloadable version of the report (a ZIP file containing a CSV). You have up to 72 hours to download the file before it is removed from our servers, and you would need to rerun your report query to get it regenerated.

Credentials are required to download the report file, there’s an example on the Developer Portal showing how to do this.

Great Ways to Use Reports API

The Reports API gives you the largest amount of information you can get from us regarding the activity on your accounts (and sub-accounts!). This means that the API lends itself to big data type applications, such as:

  • Data visualization and analysis via tools like Tableau.
  • Being part of a data pipeline implementation for data warehouses.
  • Spotting traffic trends, issues, or fraudulent cost spikes on a large scale.
  • Providing in-depth analytics to customers on their activity (via sub-accounts).
  • Testing and managing outbound campaigns (especially with SMS or Messages APIs).

Once you have access to this data, there are very few limits to what you can do with it.

Further Reading

If this introductory post has piqued your interest, then your next stop should be the complete documentation for the Reports API as well as the main overview of the Reports API where there’s even more detail about what is contained in a generated report.

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at privacy@nexmo.com.