Reports API Best Practices

This page provides best practices for effectively using the Vonage Reports API.

Optimizing Requests with Filters

Take advantage of filtering options to tailor your requests. The Reports API filters available depend on the requested product. See further details in the query parameters for the synchronous method, and in the request body for the asynchronous method.

Using filters helps retrieve only the necessary data, optimizing API calls and reducing the user's request cost.

The most popular filters are:

  • filtering by date range (date_start, date_end)
  • filtering by id to get the actual status of the exact event (message/call, etc.) - supported by synchronous endpoint only
  • filtering by phone numbers (to, from, etc.)

Best Practices for Monitoring Message Status

To monitor the latest status of the message, you should request the report using the id request parameter - this is available for the synchronous method only. It is a much more efficient method than requesting the same data several times.

Optimizing Requests with All Your Sub-Accounts

If you plan to request the report for a Master account with all its sub-accounts, and the number of sub-accounts is more than 10, consider the following flow to get your report much faster:

  1. Call the sub-accounts API to get the actual list of all sub-accounts related to your Master account ID.
  2. Call Reports API for each sub-account separately and for your Master account ID without sub-accounts.

Understanding Pricing and Pay as You Go pricing model

With the Pay as you go pricing model, you will be charged per record in the report. Refer to this page to see examples. If you request the same CDR in multiple reports, you will be charged multiple times.

To get an idea of how many CDRs you can get for a given period of time, navigate to Dashboard and then go to the Analytics in the left navigation menu. This way, it will be easier for you to estimate the price for your report.

Handling Limitations

  • Asynchronous endpoint limit - Currently, you can produce an archived report with a maximum of 1 GB. It's around 7M records. Depending on the product, the number can be higher for those with fewer columns. To reduce the number of records in one report, try to get data in chunks. You can filter your data by time period, status, phone number, etc. Check pricing for details.
  • Rate limits - Be aware of the rate limit. Reports API supports five requests per second when used asynchronously, and ten requests per second synchronously. Exceeding these limits will return an HTTP 429: Too Many Requests error.

Choosing Between the Synchronous and Asynchronous Method

If you want to get data in small chunks more quickly, use the synchronous method (It's possible to get an unlimited number of records from the sync endpoint in 1000 chunks of data).

If you plan to get larger datasets (more than 10,000 records), use the asynchronous method. The synchronous method is best for Customers who require real-time data for their dashboards or internal storages. The advantage of the asynchronous method is that it allows users to receive their reports as CSV files, which can be used for further manual analysis. Additionally, with the asynchronous report, users can get data for all their sub-accounts in one report.

Monitoring API Usage Effectively

Implement internal monitoring to track your API usage patterns, or use the Reports API with the product REPORTS-USAGE to get information about your Reports API usage. It's free of charge, and the data is available for the last 13 months - this will help you identify any potential inefficiencies, optimize your application, and stay within the planned budget.