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

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, 95^th 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

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

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

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).

Explore Media portal

Portal overview

API overview

API articles

Access group hierarchy
Caching configuration management 1.0 (deprecated)
Caching configuration management 2.0 (deprecated)
Content invalidation
Key
Origin Storage (deprecated)
Real time monitoring (RTM) (Caching)
Services hierarchy (partially deprecated)
Usage reporting
Vyvx reservations
Error responses
Sample API code

Usage reporting

Generic usage reporting

Description

Method

Schema location

Base URI

https://ws.lumen.com

URI syntax

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

Request

Response

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

Request

Response

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

Request

Response

Possible status and error messages returned to client

Usage by access group

Description

Typical use

Method

GET

Schema location

Base URI

URI syntax

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

Request

Resource

Possible status and error messages returned to client

Usage reporting—data interval

Description

Method

GET

Schema location

Base URI

URI syntax

Example 1: JSON

Request

Response

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

Request

Response

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

Request

Response

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

Request

Response

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

Request

Response

Possible status and error messages returned to client

Usage granularity rules

Caching

Origin Storage