View usage data with the Wowza Streaming Cloud REST API

Learn how to use the REST API to get usage data for an account in the Wowza Streaming Cloud™ service. Usage data includes stream processing time for transcoders, usage for stream targets and VOD streams, egress for transcoders, and peak storage.

Note: To learn how to get usage data for an ultra low latency stream target, see View ultra low latency usage with the Wowza Streaming Cloud REST API.

Usage parameters


Parameter Data Type Description
from datetime The start of the range of time you want to view. The default from is the last billing date.

For transcoder stream processing time or peak storage requests, specify YYYY-MM-DD HH:MM:SS where HH is a 24-hour clock in UTC. 

For usage requests for stream targets, VOD streams, or transcoders, specify YYYY-MM-DD HH:00:00 where HH is a 24-hour clock in UTC. The range doesn't include minutes and seconds and rounds minutes up to the hour. The maximum difference between from and to is 90 days. If you set the from query parameter without setting the to query parameter, the data returned will reflect 90 days starting at the from date, or data up to to the current day, whichever is shorter.
to datetime The end of the range of time you want to view. The default to is the end of the current day.

For transcoder stream processing time or peak storage requests, specify YYYY-MM-DD HH:MM:SS where HH is a 24-hour clock in UTC.

For usage requests for stream targets, VOD streams, or transcoders, specify YYYY-MM-DD HH:00:00 where HH is a 24-hour clock in UTC. The range doesn't include minutes and seconds and rounds minutes up to the hour. The maximum difference between from and to is 90 days. If you set the to query parameter without setting the from query parameter, the data returned will be from the past 90 days or from your last invoice date, whichever is shorter.

View usage for stream targets


Usage for stream targets is the amount of data that went through every Wowza Streaming Cloud stream target.

To view usage details for all stream targets in the account, call the resource

https://api.cloud.wowza.com/api/[version]/usage/stream_targets

Example request and response

Notes:
  • To authenticate API requests, use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
  • The curl examples below use environment variables. See Using cURL for more information on how to set these up.
  • The --data-urlencode option in the example curl commands replaces unprintable and special characters, such as spaces, curly brackets, forward slashes, and semicolons, with ASCII-safe, unambiguous characters that are understood across the Internet.
curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/stream_targets?from=2019-11-07 15:00:00&to=2019-12-05 15:00:00"
 
Note: The response is paginated with a default per_page value of 1000. For more information on paginating query results, see Get paginated query results with the Wowza Streaming Cloud REST API.

The response provides detailed information for all stream targets in the account, including the stream target ID, type of target, unique viewers, viewing time, and total bytes of usage for the target.

{
  "stream_targets": [
      {
          "id": "nlyjxjbc",
          "name": "My Stream Target",
          "archived": true,
          "type": "fastly",
          "unique_viewers": 34,
          "viewing_time": 180990,
          "bytes": 37067405516,
      },
      {
          "id": "zwry3gj7",
          "name": "My Other Stream Target",
          "archived": false,
          "type": "fastly",
          "unique_viewers": 1,
          "viewing_time": 90,
          "bytes": 27258685,
      }
  ],
  "pagination": {
      "payload_version": 2.0,
      "total_records": 6,
      "per_page": 2,
      "next_page_key": "zzvfprpf",
      "total_pages": 3
  },
  "limits": {
      "from": "2019-11-07T15:00:00.000Z",
      "to": "2019-12-05T15:00:00.000Z"
  }
}

Related requests

Fetch a summary of stream target usage for the account:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/stream_targets/summary?from=2019-08-04 15:00:00&to=2019-9-04 15:00:00"

The response provides aggregate account information for all stream targets, including unique viewers, viewing time, and bytes of usage per billing zone.

Fetch usage details for a single stream target:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/stream_targets/[stream_target_id]?from=2019-08-04 15:00:00&to=2019-9-04 15:00:00"

The response provides detailed information for a single stream target, including the stream target ID, type of target, unique viewers, viewing time, total bytes of usage for the target, and bytes of usage per billing zone.

Fetch usage data per country for a single stream target:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/stream_targets/[stream_target_id]/countries"

The response provides detailed usage information for the stream target, broken out by country. Details for each country where the stream was requested include the country code, country name, unique viewers, viewing time, total bytes of usage for the target, and bytes of usage per billing zone.

Fetch usage data per rendition for a single stream target:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/stream_targets/[stream_target_id]/renditions"

The response provides detailed usage information for the stream target, broken out by output rendition. Details for each rendition include the rendition name, unique viewers, viewing time, total bytes of usage for the target, and bytes of usage per billing zone.

View usage for transcoders


Transcoder usage (egress) includes traffic leaving Wowza Streaming Cloud for Wowza CDN and custom stream targets.

To view transcoder egress, call the resource

https://api.cloud.wowza.com/api/[version]/usage/transcoders

Example request and response

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
--data-urlencode 'from=2019-07-01 12:00:00' \
--data-urlencode 'to=2019-07-16 12:00:00' \ 
"${WSC_HOST}/api/${WSC_VERSION}/usage/transcoders"

The query returns details on all transcoder usage during the specified timeframe.

{
   "transcoders": [
     {
       "bytes": 53446778562,
       "archived": false,
       "id": "1237abcd",
       "name": "RTMP-Pull-Street",
       "transcoder_type": "transcoded",
       "billing_mode": "pay_as_you_go",
       "seconds": "13241234"
     },
     {
       "bytes": 119542733,
       "archived": true,
       "id": "1238abcd",
       "name": "RTMP Pull test",
       "transcoder_type": "transcoded",
       "billing_mode": "twentyfour_seven",
       "seconds": "23423453 "
     },
     {
       "bytes": 14109171,
       "archived": true,
       "id": "1239abcd",
       "name": "IP camera stream",
       "transcoder_type": "passthrough",
       "billing_mode": "pay_as_you_go",
       "seconds": "75686798"
     }
   ],
   "pagination": {
       "payload_version": 1.0,
       "page": 3,
       "page_first_index": 6,
       "page_last_index": 8,
       "per_page": 3,
       "total_pages": 710,
       "total_records": 2130
   },
   "limits": {
       "from": "2019-10-01T07:00:00.000Z",
       "to": "2019-10-16T11:00:00.000Z"
   }
 }

Related requests

Fetch a summary of transcoder usage for the account:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
--data-urlencode 'from=2019-07-01 12:00:00' \
--data-urlencode 'to=2019-07-16 12:00:00' \ 
"${WSC_HOST}/api/${WSC_VERSION}/usage/transcoders/summary"

The query returns aggregate usage information for all transcoders on the account during the specified timeframe

Fetch usage data for a single transcoder:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
--data-urlencode 'from=2019-07-01 12:00:00' \
--data-urlencode 'to=2019-07-16 12:00:00' \ 
"${WSC_HOST}/api/${WSC_VERSION}/usage/transcoders/[transcoder_id]]"

The query returns usage details on a single transcoder during the specified timeframe.

View peak storage


Peak storage is the greatest amount of recorded content stored in your Wowza Streaming Cloud account at any point in a given month. For example, if you create five recordings and two VOD streams in a month, and during the same month you delete two of the recordings, your peak storage will equal the total amount of data stored for the five recordings and two VOD streams.

To view peak storage, call the resource

https://api.cloud.wowza.com/api/[version]/usage/storage/peak

Example request and response

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
--data-urlencode 'from=2019-12-07 12:00:00' \
--data-urlencode 'to=2019-12-21 12:00:00' \
"${WSC_HOST}/api/${WSC_VERSION}/usage/storage/peak"

The query returns the greatest amount of bytes stored in your account at any one point in the specified timeframe.

{
   "bytes": 15130718193,
   "limits": {
       "from": "2019-12-07T00:00:00.000Z",
       "to": "2019-12-21T00:00:00.000Z"
   }
}

View usage for VOD streams


Usage for VOD streams is the amount of data that went through every Fastly stream target.

To view usage details for all VOD streams in the account, call the resource

https://api.cloud.wowza.com/api/[version]/usage/vod_streams
 
Note: The usage/vod_streams endpoint is available from v1.5 of the Wowza Streaming Cloud REST API.

Example request and response

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/vod_streams?from=2019-11-07 15:00:00&to=2019-12-05 15:00:00"

The response provides detailed information for all VOD streams in the account, including the VOD stream ID, type of target, unique viewers, viewing time, and total bytes of usage for the target.

{
  "vod_streams": [
      {
          "id": "nlyjxjbc",
          "name": "My VOD Stream",
          "archived": true,
          "type": "fastly",
          "unique_viewers": 34,
          "viewing_time": 180990,
          "bytes": 37067405516,
      },
      {
          "id": "zwry3gj7",
          "name": "My Other VOD Stream",
          "archived": false,
          "type": "fastly",
          "unique_viewers": 1,
          "viewing_time": 90,
          "bytes": 27258685,
      }
  ],
  "pagination": {
      "payload_version": 2.0,
      "total_records": 4,
      "per_page": 2,
      "next_page_key": "zlvfpmpn",
      "total_pages": 2
  },
  "limits": {
      "from": "2019-11-07T15:00:00.000Z",
      "to": "2019-12-05T15:00:00.000Z"
  }
}

Related requests

Fetch a summary of VOD stream usage for the account:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/vod_streams/summary?from=2019-08-04 15:00:00&to=2019-9-04 15:00:00"

The response provides aggregate account information for all VOD streams, including unique viewers, viewing time, and bytes of usage per billing zone.

Fetch usage details for a single VOD stream:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/vod_streams/[vod_stream_id]?from=2019-08-04 15:00:00&to=2019-9-04 15:00:00"

The response provides detailed information for a single VOD stream, including the VOD stream ID, type of target, unique viewers, viewing time, total bytes of usage for the target, and bytes of usage per billing zone.

Fetch usage data per country for a single VOD stream:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/vod_streams/[vod_stream_id]/countries"

The response provides detailed usage information for the VOD stream, broken out by country. Details for each country where the stream was requested include the country code, country name, unique viewers, viewing time, total bytes of usage for the target, and bytes of usage per billing zone.

Fetch usage data per rendition for a single VOD stream:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/usage/vod_streams/[vod_stream_id]/renditions"

The response provides detailed usage information for the VOD stream, broken out by output rendition. Details for each rendition include the rendition name, unique viewers, viewing time, total bytes of usage for the target, and bytes of usage per billing zone.