Tracking Usage

Fastevo MP2 provides endpoints to track the usage of media protection resources. You can use these endpoints to retrieve detailed metrics on network, storage, and transcoding usage. This information is useful for understanding the consumption of your project's resources and for billing or analytics purposes.

ℹ️

All usage endpoints require two query parameters, startDate and endDate, expressed in ISO 8601 format. These dates must define a period of no more than 365 days.

Overview of Usage Endpoints

The following endpoints are available to track usage metrics:

Network Usage: Retrieves data regarding the number of requests, total bytes downloaded, and cache hit rate.
Storage Usage: Provides usage information related to the number of stored objects and the total bytes stored.
Transcoding Usage: Returns details on the transcoding minutes used for various output qualities and priorities.

Each endpoint uses the same required query parameters:

startDate: The beginning of the period (inclusive).
endDate: The end of the period (inclusive).

Note: If the period between startDate and endDate exceeds 365 days, the API will return an error indicating an invalid period.

Network Usage

Endpoint

GET https://api.fastevo.com/api/v1/projects/mediaProtection/usage/network?startDate={startDate}&endDate={endDate}

Description

This endpoint returns an array of network usage data. Each record in the array includes:

collectionDate: The date when the usage was recorded.
requests: The total number of network requests during that day.
bytesDownloaded: The total number of bytes downloaded.
cacheHitRate: The percentage (from 0 to 100) indicating how many of the total requests were served by the cache (i.e., without needing to fetch data from the origin).

Example Request

GET https://api.fastevo.com/api/v1/projects/mediaProtection/usage/network?startDate=2023-09-01T00:00:00.000Z&endDate=2023-09-05T23:59:59.999Z

Example Response

[
  {
    "collectionDate": "2023-09-05T00:00:00.000Z",
    "requests": 300,
    "bytesDownloaded": 3000,
    "cacheHitRate": 20
  },
  {
    "collectionDate": "2023-09-04T00:00:00.000Z",
    "requests": 200,
    "bytesDownloaded": 2000,
    "cacheHitRate": 0
  },
  {
    "collectionDate": "2023-09-03T00:00:00.000Z",
    "requests": 100,
    "bytesDownloaded": 1000,
    "cacheHitRate": 5
  },
  {
    "collectionDate": "2023-09-02T00:00:00.000Z",
    "requests": 0,
    "bytesDownloaded": 0,
    "cacheHitRate": 0
  }
]

⚠️

Remember that if the period specified is over one year, the request will fail with an error. Also, proper authorization using the project API key is required.

Storage Usage

Endpoint

GET https://api.fastevo.com/api/v1/projects/mediaProtection/usage/storage?startDate={startDate}&endDate={endDate}

Description

This endpoint provides storage usage details in an array format where each item contains:

collectionDate: The date of the storage record.
numberOfObjects: The number of items stored.
bytesStored: The cumulative size (in bytes) of all stored items. This is calculated over the different storage types (for example, Glacier and Deep Archive).

Example Request

GET https://api.fastevo.com/api/v1/projects/mediaProtection/usage/storage?startDate=2023-09-01T00:00:00.000Z&endDate=2023-09-05T23:59:59.999Z

Example Response

[
  {
    "collectionDate": "2023-09-05T00:00:00.000Z",
    "numberOfObjects": 3000,
    "bytesStored": 90
  },
  {
    "collectionDate": "2023-09-04T00:00:00.000Z",
    "numberOfObjects": 2000,
    "bytesStored": 60
  },
  {
    "collectionDate": "2023-09-03T00:00:00.000Z",
    "numberOfObjects": 1000,
    "bytesStored": 30
  },
  {
    "collectionDate": "2023-09-02T00:00:00.000Z",
    "numberOfObjects": 0,
    "bytesStored": 0
  }
]

⚠️

If the query period exceeds 365 days, the API will respond with an error. Every request must also include valid authorization.

Transcoding Usage

Endpoint

GET https://api.fastevo.com/api/v1/projects/mediaProtection/usage/transcoding?startDate={startDate}&endDate={endDate}

Description

This endpoint returns an array of transcoding usage metrics. Each record includes:

collectionDate: The date when the transcoding usage was recorded.
outputTranscodingMinutesByQuality: An object listing the total transcoding minutes used for each output quality. Typical quality labels include "240p", "360p", "480p", "720p", and "1080p".
outputTranscodingMinutesByPriority: An object describing the transcoding minutes used keyed by priority, where priority levels range from 0 to 10.

Example Request

GET https://api.fastevo.com/api/v1/projects/mediaProtection/usage/transcoding?startDate=2023-09-01T00:00:00.000Z&endDate=2023-09-05T23:59:59.999Z

Example Response

[
  {
    "collectionDate": "2023-09-05T00:00:00.000Z",
    "outputTranscodingMinutesByQuality": {
      "240p": 15,
      "360p": 20,
      "480p": 25,
      "720p": 30,
      "1080p": 35
    },
    "outputTranscodingMinutesByPriority": {
      "0": 5,
      "1": 10,
      "2": 15,
      "3": 20,
      "4": 25,
      "5": 30,
      "6": 35,
      "7": 40,
      "8": 45,
      "9": 50,
      "10": 55
    }
  },
  {
    "collectionDate": "2023-09-04T00:00:00.000Z",
    "outputTranscodingMinutesByQuality": {
      "240p": 10,
      "360p": 15,
      "480p": 20,
      "720p": 25,
      "1080p": 30
    },
    "outputTranscodingMinutesByPriority": {
      "0": 2,
      "1": 4,
      "2": 8,
      "3": 10,
      "4": 12,
      "5": 16,
      "6": 18,
      "7": 20,
      "8": 22,
      "9": 24,
      "10": 26
    }
  }
]

⚠️

Ensure you include both startDate and endDate in your query parameters. The transcoding usage endpoint will also enforce the one-year maximum period rule.

Error Handling

If any of the usage API requests are made with an invalid period (i.e. a period longer than 365 days) or with invalid/insufficient authorization, the API will reject the request with an appropriate error message. Developers must ensure the query parameters are correctly formatted and the API key is properly set in the request headers.

Playback stats