When you use our communication APIs, server logs and transactional records of the activity are created, which are called CDRs (Call Detail Record). The Reports API enables you to download your CDRs. You can filter your CDRs based on attributes such as origin and destination phone numbers, status, time period and more. See the list of supported parameters. You can include the message body/text and download reports for any of your subaccounts.
You can use the Reports API in a wide variety of use cases, including:
- Customer billing - Download your transactions and use the included price data to determine what to bill your customers.
- Invoice reconciliation - Compare your usage data with the invoice you have received.
- Monitoring and analytics - Add CDR data to your business intelligence or analytics system to correlate it with other events.
You can query your CDRs using a wide range of filters. Data records are kept for thirteen months (maximum retention period). Records older than 13 months cannot be obtained because they are automatically deleted from the system.
Depending on your query pattern, you can choose from one of the two approaches for the Reports API:
The synchronous version is optimized for frequent and periodic retrievals of small batches of data records. Typical batch sizes range from one record to tens of thousands per query.
The asynchronous version is optimized for infrequent and large data queries. Typical batch sizes range from several thousand records to tens of millions.
The following table compares the features of the synchronous and asynchronous methods of using the Reports API:
|Feature||Reports Synchronous (GET endpoint)||Reports Asynchronous (POST endpoint)|
|Data retrieval||Returns results immediately in batches of up to 1000 records. Response contains a batch of data records and a link to the next batch (if any)||Does not return data immediately. Instead, it records a data request, processes it asynchronously, and creates a file containing all records. When the results file is ready, it returns a link to the file|
|Compression||Not applicable||CSV file is compressed for faster downloads|
|Report TTL||Not applicable||Report files are automatically deleted after 72 hours|
|Time filter||Can fetch up to 24 hours of data in one query||Can fetch up to 13 months (maximum retention period) of data in one query|
|ID filter||Can fetch one data record by its ID||Does not support ID filtering|
|Message body||Can fetch message body||Can fetch message body|
|Subaccounts||Requires a separate request for each subaccount||Requires one report request. It automatically groups data records belonging to subaccounts into one report|
|Callbacks||Not applicable||An HTTP(S) POST callback can be generated to notify when report is completed|
A note on performance: Even though the Reports API is fast and can deal with enormous amounts of data, it may become slower when trying to download data for realtime analytics. Using sensible filters can speed up processing considerably.
- SMS API
- Messages API
- Voice API
- Conversations API
- Verify API
- Number Insight API
From the 2nd November 2020, Vonage is introducing two pricing plans for all new Reports API customers. These are shown in the following table:
|Pay As You Go||0.0004€ per CDR (0.40€ per 1000 CDRs)||Charges are applied based on the volume of data retrieved.|
|Unlimited Plan||450€ per month||You can download as much data as you like, included in the single price.|
Assume you want to retrieve SMS records for the last one minute, and it turns out that there are 300 records in this time period. The total charge for this report will be the following:
Charge = 300 * 0.0004€ = 0.12€
GET Requests (create and get JSON report) can return records either by ID or by a time period they belong to. Search by ID is not time-bounded. Time period search supports ranges of up to 24 hours.
Assume you create an SMS report to retrieve one day of data and this report contains 10,000 CDRs, then the total charge for this report will be the following:
Charge = 10,000 * 0.0004€ = 4€
- Before you Begin
- Get records by UUID
- Get records by dates
- Create report
- List reports
- Get report status
- Download report file
- Cancel report
- Create a CSV report using the command line
- Create a CSV report using a graphical tool
- Get JSON records using the command line