How to request account reports

The Bandwidth numbers API allows you to automate the creation and download of certain reports related to account usage.

Available Account Reports

To list all available account report types with their ID and description, make a GET request to our List Reports API endpoint. The report ID needs to be passed in to the URL of the API request to indicate which type of report to create. This can be done through tools like Postman or cURL.

Request URL:

GET

https://dashboard.bandwidth.com/api/accounts/{accountId}/reports

cURL

curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/reports'
-u '{userName}:{password}'

Response

<ReportsResponse>
   <Reports>
      <Report>
         <Name>Report 1</Name>
         <Id>10</Id>
         <Description>Report 1 Description</Description>
      </Report>
      <Report>
         <Name>Report 2</Name>
         <Id>11</Id>
         <Description>Report 2 Description</Description>
      </Report>
   </Reports>
</ReportsResponse>

Report Details

To retrieve details for a specific report, like a description and the parameters needed to define boundaries for the report, make a GET request to our Retrieve Report API endpoint. This can be done through tools like Postman or cURL.

Request URL:

GET

https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/

{reportId}

cURL

curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}'
-u '{userName}:{password}'

Response

<ReportResponse>
   <Report>
      <Id>10</Id>
      <Name>Report 1</Name>
      <Parameters>
         <Parameter>
            <Name>Report Parameter</Name>
            <Type>Enum</Type>
            <Required>false</Required>
            <ValueFilter>Value1;Value2;</ValueFilter>
            <Values>
               <Value>
                  <InternalName>Value1</InternalName>
                  <DisplayName>Display Value2</DisplayName>
               </Value>
               <Value>
                  <InternalName>Value2</InternalName>
                  <DisplayName>Value2</DisplayName>
               </Value>
            </Values>
            <Description>Report Parameter Description</Description>
            <MultiSelectAllowed>true</MultiSelectAllowed>
            <HelpInformation>Report Parameter Help Text</HelpInformation>
         </Parameter>
      </Parameters>
   </Report>
</ReportResponse>

Request a Report

To generate a specific report, you must make a POST request to our Create Report Instance API endpoint. Response will contain a location header used to query the status of the report. This can be done through tools like Postman or cURL.

Payload

POST

https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/ {reportId}/instances

<Instance>
    <OutputFormat>pdf</OutputFormat>
    <Parameters>
        <Parameter>
            <Name>Account</Name>
            <Value>1</Value>
        </Parameter>
        <Parameter>
            <Name>Sub-account</Name>
            <Value>1</Value>
        </Parameter>
        <Parameter>
            <Name>MultiValueEnum</Name>
            <Value>value1</Value>
            <Value>value2</Value>
        </Parameter>
    </Parameters>
    <ExpiresAt>2020-11-25</ExpiresAt>
</Instance>

cURL

curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instances'
-u '{userName}:{password}'
-H 'Content-Type: application/xml'
-d '<Instance>
        <OutputFormat>pdf</OutputFormat>
        <Parameters>
            <Parameter>
                <Name>Account</Name>
                <Value>1</Value>
            </Parameter>
            <Parameter>
                <Name>Sub-account</Name>
                <Value>1</Value>
            </Parameter>
            <Parameter>
                <Name>MultiValueEnum</Name>
                <Value>value1</Value>
                <Value>value2</Value>
            </Parameter>
        </Parameters>
        <ExpiresAt>2020-11-25</ExpiresAt>
    </Instance>'

Response

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instances/789

Fetch Report Status

Since the account report request generation is asynchronous, make a GET request to our Retrieve Report Instance API endpoint to determine the status. This can be done through tools like Postman or cURL.

Request URL:

GET

https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/ {reportId}/instances/{instanceId}

cURL

curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instances/{instanceId}'
-u '{userName}:{password}'

Response

<ReportInstanceResponse>
    <Instance>
        <Id>789</Id>
        <ReportId>10</ReportId>
        <ReportName>Sample Report</ReportName>
        <OutputFormat>pdf</OutputFormat>
        <RequestedByUserName>user</RequestedByUserName>
        <RequestedAt>2022-9-16 11:05:12</RequestedAt>
        <Parameters>
            <Parameter>
                <Name>AccountId</Name>
                <Value>1</Value>
            </Parameter>
        </Parameters>
        <Status>Ready</Status>
        <ExpiresAt>2022-10-16</ExpiresAt>
    </Instance>
</ReportInstanceResponse>

Download the Report

If the report status is Ready, then you are ready to download the requested report. This can be done by making a GET request to our Download Report Instance File API endpoint. There are two possible successful responses: 200 OK or 307 Temporary Redirect.

info

Ensure that your client is configured to omit the Authorization header when following cross-origin redirects returned by this endpoint, as the redirect URL includes auth in the query parameters. Requests to the redirect url that include multiple auth mechanisms will be rejected with 400 Bad Request.

Request URL:

GET

https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/ {reportId}/instances/{instanceId}/file

cURL

curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/reports/{reportId}/instances/{instanceId}/file'
-u '{userName}:{password}'

Response types

200 - OK

The 200 response will include a Content-Disposition header indicating the filename. Downloading of the file will begin.

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=output.pdf

307 - Temporary Redirect

The 307 response will include a Location header that includes the link to the file. Follow the link in order to download the file.

HTTP/1.1 307 Temporary Redirect
Location: some_file_link

Where to next?

Now that you have learned how to request account reports, check out some of the other available actions in our guides:

• How to request billing reports