Reports Overview
Bandwidth Insights Reports let you generate detailed extracts of your accounts' activity, billing, and telephone number data. Reports can be created and downloaded from the Bandwidth App under Insights → Reports, or programmatically through the Insights Reporting API.
Report categories
Reports are grouped into three categories, which map to the tabs on the Reports page in the Bandwidth App:
| Category | What it contains |
|---|---|
| Usage | Detail records describing the activity on your accounts — voice calls (CDRs), messages (MDRs), and other usage detail records. |
| Charges | Billing detail records (BDRs) and charge summaries that show how your usage and services were rated and billed. |
| Number Details | The state of the telephone numbers and short codes on your accounts — inventory, provisioning status, and messaging configuration. |
Report domains
Each report also belongs to a domain — the Bandwidth product the report's data comes from:
| Domain | What it covers |
|---|---|
| Voice | Voice calling activity and charges — call detail records, voice usage, and billing detail records. |
| Messaging | SMS/MMS activity and charges, short code and 10DLC campaign details, and toll-free verification status. |
| Emergency | Emergency (911) call detail records and endpoint provisioning details. |
| Numbers | Telephone number inventory and telephone-number billing detail. |
Discovering the reports available to you
The specific reports available to your accounts depend on the products you use. Rather than listing every report here, use the Get Report Definitions API to discover the reports available to you. Each report definition includes a customer-facing description explaining what the report contains, along with its category, domain, supported filters, and regions. This is the same information shown on the Reports page in the Bandwidth App.
You can filter the report definitions by category, domain, and reportName to find the report you need.
How reporting works
Each report is described by a report definition — a template that specifies the report's category, domain, the filters it accepts, the regions it covers, and how far back its data goes (maxMonthsBack). You discover the definitions available to your accounts, then request a report against one of them.
Bandwidth offers two ways to retrieve report data through the API:
- Asynchronous reports — You create a report, poll for its status, and download the finished file once it is ready. Use this for large extracts delivered as a downloadable file. See the Reports Quick Start.
- Synchronous reports — You request results directly and receive the rows in the API response, a page at a time, with no file to download. See the Synchronous Reports Quick Start.
Filters and parameters
Every report definition declares the filters it supports. A filter has a name (for example receivedTime, subAccount, or campaignId), a value type, and one or more supported operators (such as EQUAL, IN, or BETWEEN). Some filters are required — for example, a time range. When a report is available in more than one region, a region value is also required.
Always inspect the report definition before requesting a report so you know which filters are available and which are required. The Get Report Definitions endpoints return this information.
Next steps
- Discover the reports available to your accounts with the Get Report Definitions API.
- Follow the Reports Quick Start to create and download a report.
- Follow the Synchronous Reports Quick Start to retrieve results synchronously.