Menu

Lumen help

Usage reporting

Description

Returns caching property, streaming ID or origin storage account usage details for an access group, SCID or network identifier. Returns the service hierarchy with usage data.         

Method

GET 

Schema location

https://ws.lumen.com/schema/cachingUsage/v1.0

https://ws.lumen.com/schema/originUsage/v1.0

Base URI

https://ws.lumen.com         

URI syntax   

/usage/cdn/(version)/(scope)?serviceType=(serviceType)[&geo=(geo)]([&dateFrom=(dateFrom)&dateTo=(dateTo)]|[dateMonth=(dateMonth)])  

cdn Required. Names CDN API as the correct engine.
version Required version.
scope
/(AG)/
or
/(AG)/(SCID)/
or
/(AG)/(SCID)/(NI)/
 Required. Scope must retain sequence that reflects hierarchy. AG is Access Group ID. NI is network identifier name.
serviceType
“caching” | “c” |
“origin” | “o”		 Required. Service type: required for scope to AG and SCID. Optional for NI.
geo
“region” | “metro”
 Optional. Return results by server region or by server metropolitan area.
dateFrom
yyyyMMddHHnn
 Optional. Date range – starting date/time
dateTo
yyyyMMddHHnn		 Optional. Date range – end date/time
dateMonth
yyyyMM		 Optional. One month. Used to report caching summary data that includes the 95%.

Example 1: Caching Usage for AG 12345 Hierarchy (Summary/Table Data) for Feb 1–4 2019

https://ws.lumen.com/usage/cdn/v1.0/12345?serviceType=caching&dateFrom=201902019000&dateTo=201902040000

<?xml version="1.0" encoding="UTF-8" ?>
<accessGroup id="12345" name="BBBN56179"
xsi:noNamespaceSchemaLocation= “(Undefined variable: Primary.API Schema URI)/cachingUsage/v1.0" xmlns:xsi="http://www.w3.org/2001X/MLSchema-instance">
<accessGroup id="12345" name="Lumen - Internal Provisioning CDN">
<apiCorrelationId>CDNPortal-1292450115423-3484
</apiCorrelationId>
<dataInterval>monthly</dataInterval>
<serviceResource>/12345</serviceResource>
<services>
<service id="BBBN56179">
<serviceResource>/12345/BBBN56179</serviceResource>
<product>CACHING</product>
<networkIdentifiers>
<ni id="cdn.lumen.com">
<serviceResource>/12345/BBBN56179/cdn.lumen.com
</serviceResource>
<summaryData>
<volume>302.79262</volume>
<averageThroughput>0.50065</averageThroughput>
<peakThroughput>3.12019</peakThroughput>
<mbps95>0.97615</mbps95>
<requests>11699692</requests>
<averageRequestsPerSecond>2.41809
</averageRequestsPerSecond>
<peakRequestsPerSecond>8.04667</peakRequestsPerSecond>
<originVolume>6.07578</originVolume>
<averageOriginThroughput>0.56257
</averageOriginThroughput>
<peakOriginThroughput>5.75245</peakOriginThroughput>
<cacheEfficiency>98.03289</cacheEfficiency>
</summaryData>
</ni>
</networkIdentifiers>
</service>
</services>
</accessGroup>         

Example 2: Caching usage summary for 12345/BBBN56179/ cdn.level3.com for December 2019

https://ws.lumen.com/usage/cdn/v1.0/12345?serviceType=caching&dateMonth=201912         

<?xml version="1.0" encoding="UTF-8" ?>
<accessGroup id="12345" name="BBBN56179"
xsi:noNamespaceSchemaLocation= “(Undefined variable: Primary.API Schema URI)/cachingUsage/v1.0" xmlns:xsi="http://www.w3.org/2001X/MLSchema-instance">
<accessGroup id="12345" name="Lumen - Internal Provisioning CDN">
<apiCorrelationId>CDNPortal-1292450115423-3484
</apiCorrelationId>
<dataInterval>monthly</dataInterval>
<serviceResource>/12345</serviceResource>
<services>
<service id="BBBN56179">
<serviceResource>/12345/BBBN56179</serviceResource>
<product>CACHING</product>
<networkIdentifiers>
<ni id="cdn.lumen.com">
<serviceResource>/12345/BBBN56179/cdn.lumen.com
</serviceResource>
<summaryData>
<volume>302.79262</volume>
<averageThroughput>0.50065</averageThroughput>
<peakThroughput>3.12019</peakThroughput>
<mbps95>0.97615</mbps95>
<requests>11699692</requests>
<averageRequestsPerSecond>2.41809
</averageRequestsPerSecond>
<peakRequestsPerSecond>8.04667</peakRequestsPerSecond>
<originVolume>6.07578</originVolume>
<averageOriginThroughput>0.56257
</averageOriginThroughput>
<peakOriginThroughput>5.75245</peakOriginThroughput>
<cacheEfficiency>98.03289</cacheEfficiency>
</summaryData>
</ni>
</networkIdentifiers>
</service>
</services>
</accessGroup>  

Example 3: Origin Usage from December 1–15, 2019

https://ws.lumen.com/usage/cdn/v1.0/12345?serviceType=o&dateFrom=201912010000&dateTo=201912152359         

<?xml version="1.0" encoding="UTF-8" ?>
<accessGroup id="12345" name="My Access Group"
xsi:noNamespaceSchemaLocation= “(Undefined variable: Primary.API Schema URI)/originUsage/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<apiCorrelationId>CDNPortal-1270071184562-8650
</apiCorrelationId>
<serviceResource>/12345</serviceResource>
<dataInterval>daily</dataInterval>
<summaryData>
<peakUsage>1014.45465</peakUsage>
</summaryData>
<services>
<service id="BBBP11111">
<serviceResource>/12345/BBBP11111</serviceResource>
<product>STORAGE</product>
<summaryData>
<peakUsage>0.0002345</peakUsage>
</summaryData>
<networkIdentifiers>
<ni id=" origin.cdn.test.net ">
<serviceResource>/12345/BBBP11111/origin.cdn.test.net
</serviceResource>
<summaryData>
<peakUsage>0.00002345</peakUsage>
</summaryData>
</ni>
<ni …/>
</networkIdentifiers>
</service>
<service …/>
</services>
<networkIdentifiers …/>
</accessGroup>         

Possible status and error messages returned to client

Additional return codes and error messages

Description

Returns a hierarchical representation of your access group data for all three services. Includes monthly, or for the current month, month-to-date data through yesterday's total. Data is updated once a day.         

Typical use

This report provides a picture of the data at each level of the access group hierarchy for all three services. Available data includes: Volume, Requests, Cache Efficiency, 95th Percentile, Peak Mbps, and Peak Requests per second.         

Method

GET         

Schema location

https://ws.lumen.com/schema/summaryUsage/v1.0         

Base URI

https://ws.lumen.com/schema/summaryUsage/v1.0         

URI syntax

/usage/cdn/(version)/(scope-AGID only)?summary=true&dateMonth=

cdn Required. Names CDN API as the correct engine.
version Required version.
scope
/(AG)/
 AG is Access Group ID.
dateMonth
yyyyMM		 Date—requested month.

Example: Access Group Usage for AG 12345 Hierarchy (Summary/Table Data) for July 2019

https://ws.lumen.com/usage/cdn/v1.0/12345?summary=true&dateMonth=201907

Returns caching usage By Access Group for AG 12345 in July 2019.

<?xml version="1.0" encoding="UTF-8" ?>
<accessGroup id="12345" name="My Access Group" xsi:noNamespaceSchemaLocation=“(Undefined variable: Primary.API Schema URI)/summaryUsage/v1.0" xmlns:xsi="http://www.w3.org/2001X/MLSchema-instance">
<accessGroup id="12345" name="Lumen - Internal Provisioning CDN">
<apiCorrelationId>CDNPortal-1282780385870-4284</apiCorrelationId>
<serviceResource>/12345</serviceResource>
<caching>
<volume>3332.36564</volume>
<requests>21219582</requests>
<mbps95>11.49775</mbps95>
</caching>
<origin>
<peakUsage>1733.15556</peakUsage>
</origin>
<accessGroups>
<accessGroup id="1235" name="L3EUInternal">
<serviceResource>/1235</serviceResource>
<caching>
<volume>2529.27034</volume>
<requests>18873353</requests>
<mbps95>7.96394</mbps95>
</caching>
<streaming>
<volume>167923.79626</volume>
<views>1213187</views>
</streaming>
<origin>
<peakUsage>450.48279</peakUsage>
</origin>
</accessGroups>
</accessGroup>         

Possible status and error messages returned to client

Additional return codes and error messages

Description

Returns usage details for an access group, SCID or network identifier, divided by the specified data interval. The data intervals available depend on the service. For example, caching usage can be selected in data intervals of 5 minutes, 1 hour or 1 day.         

Method

GET        

Schema location

https://ws.lumen.com/schema/cachingUsageDataInterval/v1.0

https://ws.lumen.com/schema/streamingUsageDataInterval/v1.0

https://ws.lumen.com/schema/originUsageDataInterval/v1.0

Base URI

https://ws.lumen.com         

URI syntax

/usage/cdn/(version)/(scope)?[serviceType=(serviceType)][&geo=(region|metro)]&dateFrom=(dateFrom)&dateTo=(dateTo)[&dataInterval=(dataInterval)][&ipVersion=(ALL|IPv4|IPv6)][&protocol=(ALL|HTTP1.1|HTTP2)][&protocolGroup=(ALL|HTTP|HTTPS)]         

cdn Required. Names CDN API as the correct engine.
version Required version.
scope
/(AG)/
or
/(AG)/(SCID)/
or
/(AG)/(SCID)/(NI)/
 Scope must retain sequence that reflects hierarchy. AG is Access Group ID. NI is network identifier name.
serviceType
“caching” | “c” |
“origin” | “o”		 Service type: required for scope to AG and SCID. Optional for NI.
geo
“region” | “metro”
 Optional. Returns results by server region or by server area for each time interval requested.

Note: Specifying both dataInterval and geo may result in very large result sets and very long API service times. For best performance, limit the time and property scope of each service call.
dateFrom yyyyMMddHHnn Date range—starting date/time
dateTo
yyyyMMddHHnn
 Date range—end date/time
dataInterval



“5min” | “hourly” |
“daily” | “monthly”
 Optional. If not specified, return service hierarchy with usage data. If specified, returns data only at the requested scope level.

Caching—5min—maximum 1 day
Hourly—maximum 20 days
Daily—maximum 90 days

Note: 95th% caching data is only returned with "monthly".
ipVersion
  • ALL
  • IPv4
  • IPv6
protocol
  • ALL
  • HTTP1.1
  • HTTP2
protocolGroup
  • ALL
  • HTTP
  • HTTPS

Example 1: JSON

https://ws.lumen.com/usage/cdn/v1.0/12345/BBBZ11111?serviceType=c&dateFrom=201901010000&dateTo=201901310000&ipVersion=IPv4&protocol=HTTP1.1&protocolGroup=HTTPS

{
"accessGroup": {
"id": 12345,
"name": "My Access Group",
"apiCorrelationId": "API-CORRELATION-ID-EXAMPLE",
"dataInterval": "daily",
"serviceResource": "/12345",
"services": [
{
"id": "BBBZ11111",
"serviceResource": "/12345/BBBZ11111",
"product": "CACHING",
"summaryData": {
"requests": "9263",
"volume": "0.00195",
"averageThroughput": "0.00007",
"peakThroughput": "0.00056",
"averageRequestsPerSecond": "0.03924",
"peakRequestsPerSecond": "0.33333",
"originVolume": "0.00000",
"averageOriginThroughput": "0.00000",
"peakOriginThroughput": "0.00000",
"cacheEfficiency": "100.00000"
},
"networkIdentifiers": [
{
"id": "my.property.net",
"serviceResource": "/12345/BBBZ11111/my.property.net",
"summaryData": { ... }
}
]
}
]
}
}         

Example 2: XML: Caching Usage Hourly dataInterval for AG 12345 from February 1–4, 2019

https://ws.lumen.com/schema/usage/cdn/v1.0/12345/BBBZ11111?serviceType=caching&dateFrom=201902010000&dateTo=201902040000&dataInterval=hourly

<?xml version="1.0" encoding="UTF-8"?>
<data xsi:noNamespaceSchemaLocation=
“(Undefined variable: Primary.API Schema URI)/cachingUsageDataInterval/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<apiCorrelationId>CDNPortal-1270071184562-8650</apiCorrelationId>
<point id="02/01/2019 00:00:00">
<item id="/12345/BBBZ11111" name="BBBZ11111">
<volume>0.00978</volume>
<averageThroughput>0.02174</averageThroughput>
<peakThroughput>0.05068</peakThroughput>
<requests>210</requests>
<averageRequestsPerSecond>0.05833</averageRequestsPerSecond>
<peakRequestsPerSecond>0.12000</peakRequestsPerSecond>
<originVolume>0.00962</originVolume>
<averageOriginThroughput>0.02138</averageOriginThroughput>
<peakOriginThroughput>0.05087</peakOriginThroughput>
<cacheEfficiency>47.95000</cacheEfficiency>
</item>
<item .../>
</point>
<point .../>
</data>>         

Example 3: XML: Caching Usage Monthly dataInterval for AG 12345 from November & December, 2019

https://ws.lumen.com/schema/usage/cdn/v1.0/12345/BBBN56179/cdn.lumen.com?serviceType=caching&dateFrom=201911010000&dateTo=201912312359&dataInterval=monthly

<?xml version="1.0" encoding="UTF-8"?>
<data xsi:noNamespaceSchemaLocation=
“(Undefined variable: Primary.API Schema URI)/cachingUsageDataInterval/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<data>
<apiCorrelationId>CDNPortal-1292451181264-8498</apiCorrelationId>
<point id="11/01/2019 00:00:00">
<item serviceResource="/12345/BBBN56179/cdn.lumen.com">
<volume>933.35894</volume>
<averageThroughput>0.55756</averageThroughput>
<peakThroughput>3.26684</peakThroughput>
<mbps95>0.23985</mbps95>
<requests>35718620</requests>
<averageRequestsPerSecond>2.66716</averageRequestsPerSecond>
<peakRequestsPerSecond>17.32333</peakRequestsPerSecond>
<originVolume>11.45859</originVolume>
<averageOriginThroughput>1.06098</averageOriginThroughput>
<peakOriginThroughput>2.32732</peakOriginThroughput>
<cacheEfficiency>98.79000</cacheEfficiency>
</item>
</point>
<point id="12/01/2019 00:00:00">
<item serviceResource="/12345/BBBN56179/cdn.lumen.com">
<volume>302.79262</volume>
<averageThroughput>0.50065</averageThroughput>
<peakThroughput>3.12019</peakThroughput>
<mbps95>0.97615</mbps95>
<requests>11699692</requests>
<averageRequestsPerSecond>2.41809</averageRequestsPerSecond>
<peakRequestsPerSecond>8.04667</peakRequestsPerSecond>
<originVolume>6.07578</originVolume>
<averageOriginThroughput>0.56257</averageOriginThroughput>
<peakOriginThroughput>5.75245</peakOriginThroughput>
<cacheEfficiency>98.03000</cacheEfficiency>
</item>
</point>
</data>         

Example 4: XML : Streaming Usage with Hourly dataInterval on February 1, 2019, from 1:00–4:00am

https://ws.lumen.com/schema/usage/cdn/v1.0/12345/BBBP11111?serviceType=s&dateFrom=201902010000&dateTo=201901040000&dataInterval=hourly

<?xml version="1.0" encoding="UTF-8"?>
<data xsi:noNamespaceSchemaLocation= “(Undefined variable: Primary.API Schema URI)/cachingUsageDataInterval/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<apiCorrelationId>CDNPortal-1270071184562-8650
</apiCorrelationId>
<point id="02/01/2019 00:00:00">
<item serviceResource="/12345/BBBP11111">
<requests>5926</requests>
<volume>0.19233</volume>
<averageConnectedPlayers>147.00000</averageConnectedPlayers>
<averageMbps>96.76320</averageMbps>
<averageDuration>1.62319</averageDuration>
<peakConnectedPlayers>37.00000</peakConnectedPlayers>
<peakMbps>35.47849</peakMbps>
</item>
<item … />
</point>
<point id="02/01/2019 01:00:00" …/>
<point id="02/01/2019 02:00:00" …/>
</data>         

Example 5: XML: Origin Usage with Daily dataInterval on February 1 & 2, 2019

https://ws.lumen.com/schema/usage/cdn/v1.0/12345/BBBR222222?serviceType=o&dateFrom=201902010000&dateTo=201902235959&dataInterval=daily

<?xml version="1.0" encoding="UTF-8"?>
<data xsi:noNamespaceSchemaLocation= "(Undefined variable: Primary.API Schema URI)/originUsageDataInterval/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<apiCorrelationId>CDNPortal-1270071184562-8650
</apiCorrelationId>
<point id="02/01/2019 00:00:00">
<item serviceResource="/12345/BBBR222222">
<volume>0.12496</volume>
</item>
<item serviceResource="/12345/BBCK11111/origin.cdn.test.net">
<volume>0.22514</volume>
</item>
</point>
<point id="02/02/2019 00:00:00" …/>
</data>         

Possible status and error messages returned to client

Additional return codes and error messages

Caching

Date range Time interval
1 day 5 min
2–20 days 1 hour
21–90 days 1 day
91+ days 1 month

Origin Storage

Date range Time interval
1–90 days 1 day
91+ days 1 month

The above tables list the allowed values when requesting usage data with a specified data interval. For example:

Caching date range: 1/1–2/4/2019, time intervals:

  • 5 min—not allowed, scope too large (because the date range is more than 1 day)
  • Hourly—not allowed, scope too large (because the date range is more than 20 days)
  • Daily—allowed.
  • Monthly—allowed. (The service will return all of January and all of February because the request spans both those months.)

Note: The month to date is considered a full month.

Likewise, ranges that are too narrow for their interval will be considered as well. For example:

Caching date range: 1/1/2019 to 1/2/2019, time intervals:

  • 5 min—allowed.
  • Hourly—allowed.
  • Daily—allowed.
  • Monthly—not allowed, date range too narrow for time interval (because the date range is fewer than 28 days).