Billing Center API v2

Access Akamai contract usage data in JSON for accounts which you have access to.

Learn more:

Overview

The Billing Center API allows you to access your website’s monthly usage over the Akamai network.

This guide details the most recent version 2 of the Billing Center API, which provides data in JSON format. For the deprecated version 1, which provides CSV data, see Billing Center API, v1.

Who should use this API

Use this API if you administer an Akamai-accelerated website, and want to develop your own tools to visualize and track how your site is being used. A range of data is available, including number of hits, megabytes served, and transmission speed. You can also use the API to compare usage data with your billing invoice.

Getting started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Billing Center, and set the access level to READ-WRITE.

  • If you want to use this API to compare your usage data with your final bill, you need a separate token to provision the Invoicing API.

  • Some API operations require contractId and productId identifiers. They are both available programmatically from the Contracts API. The Billing Center API allows access to any contract for which you have permission to view billing data.

  • Some API operations require reporting group identifiers. If you don’t already have them, they are available in the Luna Control Center’s Contract Usage CP Code Groups view. Use the Group ID to specify a valid reportingGroupId.

  • If you need help with the API, provide feedback with the Akamai developer community, or else contact your Akamai representative for help understanding your data.

Migrating from Billing API v1

The anticipated EOL of Billing Center API v1 is June 2019. Please review these key changes and update your implementations accordingly.

  • No CSV data. CSV output is no longer supported. Data is returned in JSON format.

  • No CP Code data. CP code data is now available in CP Codes and Reporting Groups API rather than Billing Center API.

  • No Reporting Groups or Contract data. Lists of billable sources (reporting groups and contracts) or lists of products related to a given reporting group are not available in Billing Center API v2 but are available in Contracts API v1. Note that the original Billing v1 operation returned only billable contracts and reporting groups. The new Contracts API returns all contracts and reporting groups, and queries to Billing Center API v2 with non-billable items will return a 403 response.

  • Cross-account data. Use the Find matching usage operation Billing Center API v2 to retrieve usage statistics, then use the CP Codes and Reporting Groups API to retrieve CP code or reporting group associations for that usage. Note that the CP Codes and Reporting Group API does not support cross-account data, so you will need to switch accounts as necessary. You can also switch accounts in Billing Center API v2 as needed to retrieve targeted data. Alternatively, you can run List usage per contract or List usage per reporting group for each account.

  • Daily or monthly data retrieval. Billing Center API v1 had separate operations for daily or monthly data. Billing API v2 uses a single operation (List usage for contracts or List usage for reporting groups) with the billingDayOnly parameter. Setting billingDayOnly=true returns one statistic for each day, the billing day total.

To retrieve a contract usage report for a list of contracts or reporting groups using Billing API v2:

  1. Run List CP codes in the CP Codes and Reporting Groups API to retrieve lists of CP codes for reporting groups or contracts.

  2. Run the Find matching usage operation to retrieve usage statistics.

To retrieve a monthly or daily contract usage report for a single contract using Billing API v2:

  • Run the List usage per contract operation. Setting billingDayOnly=true returns one statistic for each day, the billing day total.

To retrieve a monthly or daily contract usage report for a single reporting group using Billing API v2:

To retrieve the available statistics types for a given period of time for a single contract using Billing API v2:

To retrieve the available statistics types for a given period of time for a single reporting group using Billing API v2:

Resources

The Billing Center API allows you to access your website’s monthly usage over the Akamai network. Usage data is available for entire contracts, or for reporting groups, which may include CP codes from more than one contract.

See Getting started for information on how to obtain valid contractId, productId, and reportingGroupId values.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Contracts  
List usage per contract GET /billing-center-api/v2/contracts/{contractId}/products/{productId}/measures{?fromMonth,fromYear,toMonth,toYear,month,year,statisticName,billingDayOnly}
List statistics per contract GET /billing-center-api/v2/contracts/{contractId}/products/{productId}/statistics{?fromMonth,fromYear,toMonth,toYear,month,year}
Reporting Groups  
List usage per reporting group GET /billing-center-api/v2/reporting-groups/{reportingGroupId}/products/{productId}/measures{?fromMonth,fromYear,toMonth,toYear,month,year,statisticName,billingDayOnly}
List statistics per reporting group GET /billing-center-api/v2/reporting-groups/{reportingGroupId}/products/{productId}/statistics{?fromMonth,fromYear,toMonth,toYear,month,year}
Measures  
Find matching usage POST /billing-center-api/v2/measures/find

List usage per contract

This operation lists a period of usage for an entire contract. See List usage per reporting group to report on related subsets of usage. Usage is aggregated daily, with one value per statistic. Unless final is true, data may still update to reflect latent edge server traffic. This operation may yield an error if you request too much data.

GET /billing-center-api/v2/contracts/{contractId}/products/{productId}/measures{?fromMonth,fromYear,toMonth,toYear,month,year,statisticName,billingDayOnly}

Sample: /billing-center-api/v2/contracts/1-ABCD/products/1-ABC012/measures?fromMonth=10&fromYear=2014&toMonth=10&toYear=2015&month=7&year=2015&statisticName=Total%20MB&billingDayOnly=true

Parameter Type Sample Description
URL parameters
contractId String 1-ABCD Identifies the contract under which data is aggregated.
productId String 1-ABC012 Identifies the product under which data is aggregated.
Optional query parameters
billingDayOnly Boolean true Aggregates cumulative data as of the end of the billing period, typically the end of the month, otherwise the day the contract’s term expires. Supplementary data may be available when contracts are extended within a given month.
fromMonth Integer 10 The month starting the range of aggregated data. Must be paired with fromYear, toYear, and toMonth.
fromYear Integer 2014 The year starting the range of aggregated data. Must be paired with fromMonth, toYear, and toMonth.
month Integer 7 The month for which data is aggregated. Must be paired with a year value.
statisticName String Total MB Reports on a specific statistic, otherwise reports all statistics by default.
toMonth Integer 10 The month ending the range of aggregated data. Must be paired with toYear, fromYear, and fromMonth.
toYear Integer 2015 The year ending the range of aggregated data. Must be paired with toMonth, fromYear, and fromMonth.
year Integer 2015 The year for which data is aggregated. Must be paired with a month value.

Status 200 application/json

Object type: Usage

Download schema: specific-measures-list-schema.json

Response Body:

[
    {
        "date": "2015-01-01",
        "value": 1.25,
        "final": true,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    },
    {
        "date": "2015-01-02",
        "value": 1.3,
        "final": true,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    },
    {
        "date": "2015-01-03",
        "value": 1.33,
        "final": true,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    },
    {
        "date": "2015-01-04",
        "value": 1.37,
        "final": false,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    },
    {
        "date": "2015-01-05",
        "value": 1.43,
        "final": false,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    }
]

  1. Determine the appropriate contractId as described in Getting started.

  2. Determine the appropriate productId as described in Getting started.

  3. Determine the desired range of values, either for the specific year and month, or the fromYear/toYear and fromMonth/toMonth range.

  4. Optionally run the List statistics per contract operation to obtain a specific statisticName to report on.

  5. Optionally set billingDayOnly=true to aggregate data for the end of the billing period.

  6. Make a GET request to /billing-center-api/v2/contracts/{contractId}/products/{productId}/measures{?year,month,fromYear,fromMonth,toYear,toMonth,statisticName,billingDayOnly}

The response array contains Usage objects.

List statistics per contract

Optionally run this operation if there’s only one type of information you want to include in your usage report, rather than the complete set. This lists each type of reportable statistic. Availability may depend on the term of the contract, hence the need to specify them for a range of time.

GET /billing-center-api/v2/contracts/{contractId}/products/{productId}/statistics{?fromMonth,fromYear,toMonth,toYear,month,year}

Sample: /billing-center-api/v2/contracts/1-ABCD/products/1-ABC012/statistics?fromMonth=10&fromYear=2014&toMonth=10&toYear=2015&month=7&year=2015

Parameter Type Sample Description
URL parameters
contractId String 1-ABCD Identifies the contract under which data is aggregated.
productId String 1-ABC012 Identifies the product under which data is aggregated.
Optional query parameters
fromMonth Integer 10 The month starting the range of aggregated data. Must be paired with fromYear, toYear, and toMonth.
fromYear Integer 2014 The year starting the range of aggregated data. Must be paired with fromMonth, toYear, and toMonth.
month Integer 7 The month for which data is aggregated. Must be paired with a year value.
toMonth Integer 10 The month ending the range of aggregated data. Must be paired with toYear, fromYear, and fromMonth.
toYear Integer 2015 The year ending the range of aggregated data. Must be paired with toMonth, fromYear, and fromMonth.
year Integer 2015 The year for which data is aggregated. Must be paired with a month value.

Status 200 application/json

Object type: Statistic

Download schema: statistic-list-schema.json

Response Body:

[
    {
        "name": "Total MB",
        "unit": "MB"
    }
]

  1. Determine the appropriate contractId as described in Getting started.

  2. Determine the appropriate productId as described in Getting started.

  3. Determine the desired range of values, either for the specific year and month, or the fromYear/toYear and fromMonth/toMonth range.

  4. Make a GET request to /billing-center-api/v2/contracts/{contractId}/products/{productId}/statistics{?year,month,fromYear,fromMonth,toYear,toMonth}

The response array contains Statistic objects.

List usage per reporting group

This operation lists a period of usage for a reporting group. Reporting groups collect sets of CP codes under a contract, allowing you to track billing for related types of traffic rather than for the entire contract. Usage is aggregated daily, with one value per statistic. Unless final is true, data may still update to reflect latent edge server traffic. This operation may yield an error if you request too much data.

GET /billing-center-api/v2/reporting-groups/{reportingGroupId}/products/{productId}/measures{?fromMonth,fromYear,toMonth,toYear,month,year,statisticName,billingDayOnly}

Sample: /billing-center-api/v2/reporting-groups/17405/products/1-ABC012/measures?fromMonth=10&fromYear=2014&toMonth=10&toYear=2015&month=7&year=2015&statisticName=Total%20MB&billingDayOnly=true

Parameter Type Sample Description
URL parameters
reportingGroupId String 17405 Identifies the unique reporting group.
productId String 1-ABC012 Identifies the product under which data is aggregated.
Optional query parameters
billingDayOnly Boolean true Aggregates cumulative data as of the end of the billing period, typically the end of the month, otherwise the day the contract’s term expires. Supplementary data may be available when contracts are extended within a given month.
fromMonth Integer 10 The month starting the range of aggregated data. Must be paired with fromYear, toYear, and toMonth.
fromYear Integer 2014 The year starting the range of aggregated data. Must be paired with fromMonth, toYear, and toMonth.
month Integer 7 The month for which data is aggregated. Must be paired with a year value.
statisticName String Total MB Reports on a specific statistic, otherwise reports all statistics by default.
toMonth Integer 10 The month ending the range of aggregated data. Must be paired with toYear, fromYear, and fromMonth.
toYear Integer 2015 The year ending the range of aggregated data. Must be paired with toMonth, fromYear, and fromMonth.
year Integer 2015 The year for which data is aggregated. Must be paired with a month value.

Status 200 application/json

Object type: Usage

Download schema: specific-measures-list-schema.json

Response Body:

[
    {
        "date": "2015-01-01",
        "value": 1.25,
        "final": true,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    },
    {
        "date": "2015-01-02",
        "value": 1.3,
        "final": true,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    },
    {
        "date": "2015-01-03",
        "value": 1.33,
        "final": true,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    },
    {
        "date": "2015-01-04",
        "value": 1.37,
        "final": false,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    },
    {
        "date": "2015-01-05",
        "value": 1.43,
        "final": false,
        "statistic": {
            "name": "Total MB",
            "unit": "MB"
        }
    }
]

  1. Determine the appropriate reportingGroupId as described in Getting started.

  2. Determine the appropriate productId as described in Getting started.

  3. Determine the desired range of values, either for the specific year and month, or the fromYear/toYear and fromMonth/toMonth range.

  4. Optionally run the List statistics per reporting group operation to obtain a specific statisticName to report on.

  5. Optionally set billingDayOnly=true to aggregate data for the end of the billing period.

  6. Make a GET request to /billing-center-api/v2/reporting-groups/{reportingGroupId}/products/{productId}/measures{?year,month,fromYear,fromMonth,toYear,toMonth,statisticName,billingDayOnly}.

The response array contains Usage objects.

List statistics per reporting group

Optionally run this operation if there’s only one type of information you want to include in a reporting group’s usage report, rather than the complete set. Availability of reportable statistics may depend on the term of the contract, hence the need to specify them for a range of time.

GET /billing-center-api/v2/reporting-groups/{reportingGroupId}/products/{productId}/statistics{?fromMonth,fromYear,toMonth,toYear,month,year}

Sample: /billing-center-api/v2/reporting-groups/17405/products/1-ABC012/statistics?fromMonth=10&fromYear=2014&toMonth=10&toYear=2015&month=7&year=2015

Parameter Type Sample Description
URL parameters
reportingGroupId String 17405 Identifies the unique reporting group.
productId String 1-ABC012 Identifies the product under which data is aggregated.
Optional query parameters
fromMonth Integer 10 The month starting the range of aggregated data. Must be paired with fromYear, toYear, and toMonth.
fromYear Integer 2014 The year starting the range of aggregated data. Must be paired with fromMonth, toYear, and toMonth.
month Integer 7 The month for which data is aggregated. Must be paired with a year value.
toMonth Integer 10 The month ending the range of aggregated data. Must be paired with toYear, fromYear, and fromMonth.
toYear Integer 2015 The year ending the range of aggregated data. Must be paired with toMonth, fromYear, and fromMonth.
year Integer 2015 The year for which data is aggregated. Must be paired with a month value.

Status 200 application/json

Object type: Statistic

Download schema: statistic-list-schema.json

Response Body:

[
    {
        "name": "Total MB",
        "unit": "MB"
    }
]

  1. Determine the appropriate reportingGroupId as described in Getting started.

  2. Determine the appropriate productId as described in Getting started.

  3. Determine the desired range of values, either for the specific year and month, or the fromYear/toYear and fromMonth/toMonth range.

  4. Make a GET request to /billing-center-api/v2/reporting-groups/{reportingGroupId}/products/{productId}/statistics{?year,month,fromYear,fromMonth,toYear,toMonth}

The response array contains Statistic objects.

Find matching usage

List usage data matching any criteria specified by a Query object. The query needs to specify at least one contractId or reportingGroupId value. This operation may yield an error if you request too much data.

POST /billing-center-api/v2/measures/find

Content-Type: application/json

Object type: Query

Download schema: measures-find-schema.json

Request Body:

{
    "month": 3,
    "year": 2017,
    "contractIds": [
        "1-3CV382"
    ],
    "reportingGroupIds": [
        3466
    ],
    "productIds": [
        "B-3-4D5VW3"
    ],
    "statisticTypes": [
        "Total MB"
    ]
}

Status 200 application/json

Object type: Usage

Download schema: measures-list-schema.json

Response Body:

[
    {
        "date": "2017-03-01",
        "value": 6.696,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-02",
        "value": 6.822,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-03",
        "value": 6.778,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-04",
        "value": 6.857,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-05",
        "value": 6.876,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-06",
        "value": 6.876,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-31",
        "value": 5.024,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-01",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-02",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-03",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-04",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-05",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-06",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-31",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-01",
        "value": 396806,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-02",
        "value": 819520,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-03",
        "value": 1223097,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-04",
        "value": 1646177,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-05",
        "value": 2072466,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-06",
        "value": 2490212,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-31",
        "value": 3045007,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-01",
        "value": 86093.599,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-02",
        "value": 141229.362,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-03",
        "value": 171406.915,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-04",
        "value": 210410.594,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-05",
        "value": 249726.839,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-06",
        "value": 287518.192,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-31",
        "value": 342557.541,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-01",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-02",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-03",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-04",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-05",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-06",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-31",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-01",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-02",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-03",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-04",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-05",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-06",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-31",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-01",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-02",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-03",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-04",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-05",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-06",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-31",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-01",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-02",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-03",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-04",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-05",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-06",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-31",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    }
]

  1. Create a Query request object. It needs a specified month and year, and at least one identifier in the contractIds or reportingGroupIds arrays.

  2. POST the object to /billing-center-api/v2/measures/find.

The response array contains Usage objects.

Data

This section details the data structures the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

✓ Member is required in requests, or always present in responses, even if its value is empty or null.
○ Member is optional, and may be omitted in some cases.
✗ Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Statistic

Contains metadata that characterizes usage data.

Download schema: statistic-schema.json

Sample GET response:

[
    {
        "name": "Total MB",
        "unit": "MB"
    }
]

Statistic members

Member Type Required Description
Statistic: Contains metadata that characterizes usage data.
name String ✓ Identifies the type of data included in a Usage report.
unit String ✓ Specifies the unit system for the Usage report’s value.

Usage

Specifies daily aggregated usage data.

Download schema: measure-schema.json, specific-measure-schema.json

Sample GET response:

[
    {
        "date": "2017-03-01",
        "value": 6.696,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-02",
        "value": 6.822,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-03",
        "value": 6.778,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-04",
        "value": 6.857,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-05",
        "value": 6.876,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-06",
        "value": 6.876,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-31",
        "value": 5.024,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-01",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-02",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-03",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-04",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-05",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-06",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-31",
        "value": 734.174,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-01",
        "value": 396806,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-02",
        "value": 819520,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-03",
        "value": 1223097,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-04",
        "value": 1646177,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-05",
        "value": 2072466,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-06",
        "value": 2490212,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-31",
        "value": 3045007,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-01",
        "value": 86093.599,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-02",
        "value": 141229.362,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-03",
        "value": 171406.915,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-04",
        "value": 210410.594,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-05",
        "value": 249726.839,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-06",
        "value": 287518.192,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-31",
        "value": 342557.541,
        "productId": "B-3-4D5VW3",
        "contractId": "1-3CV382",
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-01",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-02",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-03",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-04",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-05",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-06",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-31",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "95/5 Mbps"
        }
    },
    {
        "date": "2017-03-01",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-02",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-03",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-04",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-05",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-06",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-31",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Mbps",
            "name": "Peak Mbps"
        }
    },
    {
        "date": "2017-03-01",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-02",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-03",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-04",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-05",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-06",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-31",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "Hits",
            "name": "Total Hits"
        }
    },
    {
        "date": "2017-03-01",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-02",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-03",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-04",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-05",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-06",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    },
    {
        "date": "2017-03-31",
        "value": 0,
        "productId": "B-3-4D5VW3",
        "reportingGroupId": 3466,
        "final": false,
        "statistic": {
            "unit": "MB",
            "name": "Total MB"
        }
    }
]

Usage members

Member Type Required Description
Usage: Specifies daily aggregated usage data.
contractId String ○ Identifies the contract enabling the usage.
date String ✓ ISO 8601 date for when the usage occurred.
final Boolean ✓ Whether all usage data has been received from edge servers, and is no longer subject to updates. The latency to calculate final data may vary, but usually takes several days.
productId String ○ Identifies the product enabling the usage.
reportingGroupId Number ○ Identifies the reporting group for the usage.
statistic Usage.statistic ✓ The Statistic measured for the usage.
value Number ✓ Provides the raw measure of numeric usage data.
Usage.statistic: The Statistic measured for the usage.
name String ✓ Identifies the type of data included in a Usage report.
unit String ✓ Specifies the unit system for the Usage report’s value.

Query

A query object to filter usage data.

Download schema: measures-find-schema.json

Sample GET response:

{
    "month": 3,
    "year": 2017,
    "contractIds": [
        "1-3CV382"
    ],
    "reportingGroupIds": [
        3466
    ],
    "productIds": [
        "B-3-4D5VW3"
    ],
    "statisticTypes": [
        "Total MB"
    ]
}

Query members

Member Type Required Description
Query: A query object to filter usage data.
contractIds Array ○ Filter data to the specified set of contract identifiers, at least one item if specified. Otherwise if omitted, you need to specify a set of reportingGroupIds.
month Integer ✓ The month (1–12) for which to aggregate data.
productIds Array ○ Filter data to the specified set of product identifiers. An empty array produces unfiltered results, the same as omitting the member.
reportingGroupIds Array ○ Filter data to the specified set of reporting group identifiers, at least one item if specified. Otherwise if omitted, you need to specify a set of contractIds.
statisticTypes Array ○ Statistics for which you want to retrieve data, each corresponding to a Statistic’s name value. An empty array produces unfiltered results, the same as omitting the member.
year Integer ✓ The year for which to aggregate data.

Errors

This section tells you what you need to know about the Billing Center API’s error response format, and details the range of HTTP status codes the API produces.

Error responses

The API produces JSON errors as in the following sample. See the sections below for details on each data member.

{
  "details": [
    {
      "field": "year",
      "code": "year.date.year.missing",
      "message": "Month parameter cannot be provided without year parameter.",
      "data": {
        "field": "year",
        "value": "null"
      }
    }
  ],
  "code": "validation.failure",
  "title": "Validation failure",
  "incidentId": "361cd072-e213-4c4e-984d-631be108a1fe",
  "resolution": null,
  "helpUrl": null
}

Error members

Member Type Description
Required
details Error.details[] Each array member object encodes context for the failed request, such as malformed query parameter field values.
code String A descriptive code that corresponds to overall HTTP status.
incidentId String A logging key useful when communicating about problems with Technical Support representatives.
title String A descriptive title that corresponds to overall HTTP status.
Optional
helpUrl String Deprecated.
resolution String Deprecated.

Error.details

Member Type Description
Required
code String A descriptive identifier for each problem.
message String A description of the problem.
Optional
data Object A loosely structured object that, when available, encapsulates the set of erroneous input values.
field String Indicates the request’s parameter field for which there is a problem.

HTTP status codes

The API produces the following set of HTTP status codes for both success and failure scenarios:

Code Description
200 Successful request.
201 Resource successfully created.
401 Authorization error.
403 Access is forbidden.
404 Resource not found.
500 Server error.

Last modified: 1/10/2019