Skip to content

README.md

Latest commit

 

History

History
309 lines (197 loc) · 108 KB

README.md

File metadata and controls

309 lines (197 loc) · 108 KB

Metrics

Overview

Operations involving metrics

Available Operations

list_breakdown_values

Retrieves breakdown values for a specified metric and timespan, allowing you to analyze the performance of your content based on various dimensions. It provides insights into how different factors contribute to the overall metrics.

How it works

  1. Before using this endpoint, you can call the List Dimensions endpoint to retrieve all available dimensions that can be used in your query.

  2. Send a GET request to this endpoint with the required metricId and other query parameters.

  3. You receive a response containing the breakdown values for the specified metric, grouped and filtered according to your parameters.

  4. Upon successful retrieval, the response includes the breakdown values based on the specified parameters. Note that the time values ( totalWatchTime and totalPlayingTime ) are in milliseconds

Example

A developer wants to analyze how watch time varies across different device types. By calling this endpoint for the playing_time metric and filtering by device_type, they can understand how engagement differs between mobile, desktop, and tablet users. This data guides optimization efforts for different platforms.

Key fields in response

  • views: The count of views based based on the applied filters.

  • value: The specific metric value calculated based on the applied filters.

  • totalWatchTime: Total time watched across all views, represented in milliseconds.

  • totalPlayTime: Total time spent playing the video, represented in milliseconds.

  • field: The grouping field value based on the groupBy parameter.

Related guide: Understand data definitions

Example Usage

import os
import sys
import json

# Add the src directory to the Python path so we can import fastpix_python
sys.path.append(os.path.join(os.path.dirname(__file__), "..", "src"))

from fastpix_python import Fastpix, models

with Fastpix(
    security=models.Security(
        username="your-access-token",
        password="your-secret-key",
    ),
) as fastpix:

    res = fastpix.metrics.list_breakdown_values(metric_id="quality_of_experience_score", timespan="24:hours", filterby="browser_name:Chrome", limit=10, offset=1, group_by="browser_name", order_by="views", sort_order="asc", measurement="avg")

    # Handle response
    print(json.dumps(res.model_dump(mode="json", by_alias=True), indent=2))

Parameters

Parameter Type Required Description Example
metric_id models.ListBreakdownValuesMetricID ✔️ Pass metric Id
 quality_of_experience_score
timespan Optional[models.ListBreakdownValuesTimespan] ➖ This parameter specifies the time span between which the video views list must be retrieved by. You can provide either from and to unix epoch timestamps or time duration. The scope of duration is between 60 minutes to 30 days.

Accepted formats are:

array of epoch timestamps for example
timespan[]=1498867200&timespan[]=1498953600

duration string for example
timespan[]=24:hours or timespan[]=7:days
 24:hours
filterby Optional[str] ➖ Pass the dimensions and their corresponding values you want to filter the views by. For excluding the values in the filter we can pass "!" before the filter value. The list of filters can be obtained from list of dimensions endpoint.
Example Values : [ browser_name:Chrome , os_name:macOS , !device_name:Galaxy ]
 browser_name:Chrome
limit Optional[int] ➖ Pass the limit to display only the rows specified by the value.
 10
offset Optional[int] ➖ Pass the offset value to indicate the page number.
 1
group_by Optional[str] ➖ Pass this value to group the metrics list by.
Possible Values : ["browser_name", "browser_version", "os_name","os_version" , "device_name", "device_model", "device_type", "device_manufacturer", "player_remote_played",player_name", "player_version", "player_software_name", "player_software_version", "player_resolution", "fp_sdk","fp_sdk_version", "player_autoplay_on", "player_preload_on","video_title", "video_id", "video_series" , "fp_playback_id","fp_live_stream_id", "media_id","video_source_stream_type", "video_source_type", "video_encoding_variant", "experiment_name", "sub_property_id", "drm_type","asn_name", "cdn", "video_source_hostname", "connection_type", "view_session_id","continent","country", "region","viewer_id", "error_code", "exit_before_video_start", "view_has_ad", "video_startup_failed" , "page_context", "playback_failed".]
 browser_name
order_by Optional[str] ➖ Pass this value to order the metrics list by.
 views
sort_order Optional[models.ListBreakdownValuesSortOrder] ➖ The order direction to sort the metrics list by.
 asc
measurement Optional[str] ➖ The measurement for the given metrics.
Possible Values : [95th, median, avg, count or sum]
 avg
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ListBreakdownValuesResponse

Errors

Error Type Status Code Content Type
errors.FastpixDefaultError 4XX, 5XX */*

list_overall_values

Retrieves overall values for a specified metric, providing summary statistics that help you understand the performance of your content. The response includes key metrics such as totalWatchTime, uniqueViews, totalPlayTime and totalViews.

How it works

  1. Before using this endpoint, you can call the list dimensions endpoint to retrieve all available dimensions that can be used in your query.

  2. Send a GET request to this endpoint with the required metricId and other query parameters.

  3. You receive a response containing the overall values for the specified metric, which may vary based on the applied filters.

Key fields in response

  • value: The specific metric value calculated based on the applied filters.
  • totalWatchTime: Total time watched across all views, represented in milliseconds.
  • uniqueViews: The count of unique viewers who interacted with the content.
  • totalViews: The total number of views recorded.
  • totalPlayTime: Total time spent playing the video, represented in milliseconds.
  • globalValue: A global metric value that reflects the overall performance of the specified metric across the entire dataset for the given timespan. This value is not affected by specific filters.

Related guide: Understand data definitions

Example Usage

import os
import sys
import json

# Add the src directory to the Python path so we can import fastpix_python
sys.path.append(os.path.join(os.path.dirname(__file__), "..", "src"))

from fastpix_python import Fastpix, models

with Fastpix(
    security=models.Security(
        username="your-access-token",
        password="your-secret-key",
    ),
) as fastpix:

    res = fastpix.metrics.list_overall_values(metric_id="quality_of_experience_score", measurement="avg", timespan="24:hours", filterby="browser_name:Chrome")

    # Handle response
    print(json.dumps(res.model_dump(mode="json", by_alias=True), indent=2))

Parameters

Parameter Type Required Description Example
metric_id models.ListOverallValuesMetricID ✔️ Pass metric Id
 quality_of_experience_score
measurement Optional[str] ➖ The measurement for the given metrics.
Possible Values : [95th, median, avg, count or sum]
 avg
timespan Optional[models.ListOverallValuesTimespan] ➖ This parameter specifies the time span between which the video views list must be retrieved by. You can provide either from and to unix epoch timestamps or time duration. The scope of duration is between 60 minutes to 30 days.

Accepted formats are:

array of epoch timestamps for example
timespan[]=1498867200&timespan[]=1498953600

duration string for example
timespan[]=24:hours or timespan[]=7:days
 24:hours
filterby Optional[str] ➖ Pass the dimensions and their corresponding values you want to filter the views by. For excluding the values in the filter we can pass "!" before the filter value. The list of filters can be obtained from list of dimensions endpoint.
Example Values : [ browser_name:Chrome , os_name:macOS , !device_name:Galaxy ]
 browser_name:Chrome
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ListOverallValuesResponse

Errors

Error Type Status Code Content Type
errors.FastpixDefaultError 4XX, 5XX */*

get_timeseries_data

This endpoint retrieves timeseries data for a specified metric, providing insights into how the metric values change over time. The response includes an array of data points, each representing the metrics value at specific intervals.

Key fields in response

  • intervalTime: The timestamp for the data point indicating when the metric value was recorded.
  • metricValue: The value of the specified metric at the given interval, reflecting the performance or engagement level during that time.
  • numberOfViews: The total number of views recorded during that interval, providing context for the metric value.

Example Usage

import os
import sys
import json

# Add the src directory to the Python path so we can import fastpix_python
sys.path.append(os.path.join(os.path.dirname(__file__), "..", "src"))

from fastpix_python import Fastpix, models

with Fastpix(
    security=models.Security(
        username="your-access-token",
        password="your-secret-key",
    ),
) as fastpix:

    res = fastpix.metrics.get_timeseries_data(metric_id="quality_of_experience_score", group_by="minute", sort_order="asc", measurement="avg", timespan="24:hours", filterby="browser_name:Chrome")

    # Handle response
    print(json.dumps(res.model_dump(mode="json", by_alias=True), indent=2))

Parameters

Parameter Type Required Description Example
metric_id models.GetTimeseriesDataMetricID ✔️ Pass metric Id
 quality_of_experience_score
group_by Optional[models.GroupBy] ➖ Pass this value to group the metrics list by.
 minute
sort_order Optional[models.GetTimeseriesDataSortOrder] ➖ The order direction to sort the metrics list by.
 asc
measurement Optional[str] ➖ The measurement for the given metrics.
Possible Values : [95th, median, avg, count or sum]
 avg
timespan Optional[models.GetTimeseriesDataTimespan] ➖ This parameter specifies the time span between which the video views list must be retrieved by. You can provide either from and to unix epoch timestamps or time duration. The scope of duration is between 60 minutes to 30 days.

Accepted formats are:

array of epoch timestamps for example
timespan[]=1498867200&timespan[]=1498953600

duration string for example
timespan[]=24:hours or timespan[]=7:days
 24:hours
filterby Optional[str] ➖ Pass the dimensions and their corresponding values you want to filter the views by. For excluding the values in the filter we can pass "!" before the filter value. The list of filters can be obtained from list of dimensions endpoint.
Example Values : [ browser_name:Chrome , os_name:macOS , !device_name:Galaxy ]
 browser_name:Chrome
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetTimeseriesDataResponse

Errors

Error Type Status Code Content Type
errors.FastpixDefaultError 4XX, 5XX */*

list_comparison_values

This endpoint lets you to compare multiple metrics across specified dimensions. You can specify the metrics you want to compare in the query parameters, and the response includes the relevant metrics for the specified dimensions.

Key fields in response

  • value: The specific metric value calculated based on the applied filters.
  • type: The data unit or format type (for example, "number", "milliseconds", "percentage").
  • name: The display name of the metric (for example, "Views", "Overall Score").
  • metric: The metric field represents the name of the Key Performance Indicator (KPI) being tracked or analyzed. It identifies a specific measurable aspect of the video playback experience, such as buffering time, video start failure rate, or playback quality.
  • items: Nested breakdown of related metrics for more detailed analysis.
  • measurement: Defines the aggregation type (for example, "avg", "sum", "median", "95th").

How it works

  1. Before making a request to this endpoint, call the list dimensions endpoint to obtain all available dimensions that can be used for comparison.

  2. Send a GET request to this endpoint with the desired metrics specified in the query parameters.

  3. You Receive a response containing the comparison values for the specified metrics across the selected dimensions.

Related guide: Compare metrics in dashboard

Example Usage

import os
import sys
import json

# Add the src directory to the Python path so we can import fastpix_python
sys.path.append(os.path.join(os.path.dirname(__file__), "..", "src"))

from fastpix_python import Fastpix, models

with Fastpix(
    security=models.Security(
        username="your-access-token",
        password="your-secret-key",
    ),
) as fastpix:

    res = fastpix.metrics.list_comparison_values(timespan="24:hours", filterby="browser_name:Chrome", dimension="browser_name", value="Chrome")

    # Handle response
    print(json.dumps(res.model_dump(mode="json", by_alias=True), indent=2))

Parameters

Parameter Type Required Description Example
timespan Optional[models.ListComparisonValuesTimespan] ➖ This parameter specifies the time span between which the video views list must be retrieved by. You can provide either from and to unix epoch timestamps or time duration. The scope of duration is between 60 minutes to 30 days.

Accepted formats are:

array of epoch timestamps for example
timespan[]=1498867200&timespan[]=1498953600

duration string for example
timespan[]=24:hours or timespan[]=7:days
 24:hours
filterby Optional[str] ➖ Pass the dimensions and their corresponding values you want to filter the views by. For excluding the values in the filter we can pass "!" before the filter value. The list of filters can be obtained from list of dimensions endpoint.
Example Values : [ browser_name:Chrome , os_name:macOS , !device_name:Galaxy ]
 browser_name:Chrome
dimension Optional[models.Dimension] ➖ The dimension id in which the views are watched.
 browser_name
value Optional[str] ➖ The value for the selected dimension.
For example:
If dimension is browser_name, the value could be Chrome , Firefox etc .
If dimension is os_name, the value could be macOS , Windows etc .
 Chrome
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ListComparisonValuesResponse

Errors

Error Type Status Code Content Type
errors.FastpixDefaultError 4XX, 5XX */*