Reports Quick Start

This guide walks through generating a report with the Bandwidth Insights Reporting API. Reports are generated asynchronously: you create a report, poll for its status, and download the finished file once it is ready.

Assumptions

• You have a Bandwidth account with Insights enabled.
• You have API credentials for authenticating your requests.

Authentication

All Reporting API requests are made against the base URL https://insights.bandwidth.com/api. Authenticate each request with a Bearer token:

Authorization: Bearer <token>

HTTP Basic authentication (username:password) is also supported:

Authorization: Basic <base64-encoded username:password>

The reporting workflow

The asynchronous report lifecycle has four steps:

1. Find a report definition to learn which reports are available and what filters they accept.
2. Create a report against a definition.
3. Poll for status until the report finishes processing.
4. Download the file when the report is complete.

Step 1: Find a report definition

A report definition is the template for a report. Use Get Report Definitions to list the definitions available to your accounts and inspect the filters, regions, and history range (maxMonthsBack) each one supports. All query parameters are optional — omit them to list every definition available to you, or narrow the list with category, domain, and reportName.

GET /v1/reportDefinitions?category=USAGE&domain=MESSAGING

{
    "links": [],
    "data": {
        "reportDefinitions": [
            {
                "category": "USAGE",
                "domain": "MESSAGING",
                "reportName": "Messaging Detail Records (MDRs)",
                "description": "Message detail records (MDRs) provides details for all the SMS message segments and MMS messages associated with your account. Data may be delayed by a few hours.",
                "regions": ["US"],
                "maxMonthsBack": 12,
                "filters": [
                    {
                        "filterName": "receivedTime",
                        "validationType": "ISO8601_RANGE",
                        "required": true
                    },
                    {
                        "filterName": "subAccount",
                        "validationType": "STRING",
                        "operator": "IN",
                        "required": false
                    }
                ]
            }
        ]
    },
    "errors": []
}

A report is identified by its category, domain, and reportName, so take note of all three from the definition — you will pass them in the create-report request in Step 2. Also note which filters are marked required and the regions the report is available in.

Step 2: Create a report

Call Create Report with the report's category, domain, and reportName, the accountIds to include, and the filters you want to apply. The filters object maps each filter name to an array of values.

• You must supply every filter marked required: true in the report definition. Use each filter's validationType and supported operators (from the definition) to construct valid values.
• If the report is available in more than one region, you must include a region. If only one region is available, it is used automatically.

POST /v1/reports

{
    "category": "USAGE",
    "domain": "MESSAGING",
    "reportName": "Messaging Detail Records (MDRs)",
    "accountIds": ["123456"],
    "filters": {
        "receivedTime": ["2024-01-01T00:00:00Z", "2024-01-31T23:59:59Z"]
    },
    "region": "US"
}

The response returns the newly created report with a reportId and an initial status of PROCESSING. Save the reportId — you will use it to track and download the report. A reportDownload link is not returned yet; it appears once the report's status is COMPLETED (see Step 3).

{
    "links": [],
    "data": {
        "reportId": "67a95525-4618-418b-ad8b-4ddd8562ad37",
        "requestedAt": "2024-01-18T17:38:37.041444Z",
        "status": "PROCESSING",
        "report": {
            "category": "USAGE",
            "domain": "MESSAGING",
            "reportName": "Messaging Detail Records (MDRs)"
        }
    },
    "errors": []
}

Step 3: Poll for status

Reports take time to generate. Use Get Report Status to check on a report until its status becomes terminal.

GET /v1/reports/67a95525-4618-418b-ad8b-4ddd8562ad37

{
    "links": [
        {
            "rel": "reportDownload",
            "href": "https://insights.bandwidth.com/api/v1/reports/67a95525-4618-418b-ad8b-4ddd8562ad37/file"
        }
    ],
    "data": {
        "reportId": "67a95525-4618-418b-ad8b-4ddd8562ad37",
        "requestedAt": "2024-01-18T17:38:37.041444Z",
        "completedAt": "2024-01-18T17:39:12.512900Z",
        "status": "COMPLETED",
        "fileName": "report123.zip"
    },
    "errors": []
}

The status field can be:

Status	Meaning
PROCESSING	The report is still being generated. Keep polling.
COMPLETED	The report is ready to download.
NO_RESULTS	The report finished but matched no data for the given filters.
FAILED	The report could not be generated.

Step 4: Download the report file

Once the status is COMPLETED, call Get Report File to download the report. The response is a .zip archive; save it using the file name from the Content-Disposition header and unzip it to obtain the report CSV file(s).

GET /v1/reports/67a95525-4618-418b-ad8b-4ddd8562ad37/file

Content-Type: application/zip
Content-Disposition: attachment; filename="report123.zip"
Content-Length: 12345

For example, download the file with curl (saving it under the name from Content-Disposition) and unzip it:

# -OJ saves the file using the Content-Disposition filename
curl -OJ -H "Authorization: Bearer <token>" \
  https://insights.bandwidth.com/api/v1/reports/67a95525-4618-418b-ad8b-4ddd8562ad37/file

# unzip the downloaded archive to get the report CSV(s)
unzip report123.zip

Retrieving report history

Use Get Reports to see the reports previously created for one or more accounts in a given category. This is useful for finding the reportId of an earlier report so you can check its status or re-download its file. Both accountIds and category are required.

GET /v1/reports?accountIds=123456&category=USAGE

{
    "links": [],
    "data": {
        "totalCount": 1,
        "reports": [
            {
                "reportId": "67a95525-4618-418b-ad8b-4ddd8562ad37",
                "requestedAt": "2024-01-18T17:38:37.041444Z",
                "completedAt": "2024-01-18T17:39:12.512900Z",
                "status": "COMPLETED",
                "fileName": "report123.zip"
            }
        ]
    },
    "errors": []
}

Next steps

• See the Reports Overview for the report categories and domains, and use Get Report Definitions to discover the reports available to your accounts.
• Need results returned directly in the response instead of a downloadable file? See the Synchronous Reports Quick Start.
• Explore the full Insights API Reference.