FastPix Developer Documentation

How it works

Before using this endpoint, you can call the List Dimensions endpoint to retrieve all available dimensions that can be used in your query.
Send a GET request to this endpoint with the required metricId and other query parameters.
You receive a response containing the breakdown values for the specified metric, grouped and filtered according to your parameters.
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

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 <a href="https://fastpix.com/docs/video-data-api/dimensions/list-dimensions">List Dimensions</a> 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: <a href="https://fastpix.com/docs/concepts/understand-data-definitions">Understand data definitions</a>

Authentication

AuthorizationBasic

FastPix APIs are secured with Basic Authentication. Use your Access Token ID as the username and Secret Key as the password in the Authorization header of each API request.

Username: Access Token ID
Password: Secret Key

Activate your FastPix account to generate your API credentials. See the guide here

FastPix APIs are secured with Basic Authentication. Use your Access Token ID as the username and Secret Key as the password in the Authorization header of each API request. - <b>Username:</b> Access Token ID - <b>Password:</b> Secret Key Activate your FastPix account to generate your API credentials. <a href="https://fastpix.com/docs/getting-started/activate-your-account" target="_blank">See the guide here</a>

Path parameters

metricIdenumRequired

Pass metric Id

Query parameters

timespan[]enumOptional

Accepted formats are:

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

duration string for example
timespan[]=24:hours or timespan[]=7:days

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`

filterby[]stringOptional

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 ]

limitintegerOptionalDefaults to 10

Pass the limit to display only the rows specified by the value.

offsetintegerOptionalDefaults to 1

Pass the offset value to indicate the page number.

groupBystringOptional

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”.]

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".]

orderBystringOptionalDefaults to views

Pass this value to order the metrics list by.

sortOrderenumOptionalDefaults to asc

The order direction to sort the metrics list by.

Allowed values:

measurementstringOptionalDefaults to avg

The measurement for the given metrics. Possible Values : [95th, median, avg, count or sum]

Response

Get filter/ dimension value details by dimension name.

successboolean

Shows the request status. Returns true for success and false for failure.

metadataobject

Retrieves breakdown values for a specified metric and timespan

datalist of objects

Retrieves breakdown values for a specified metric and timespan

paginationobject

Pagination organizes content into pages for better readability and navigation.

timespanlist of integers

The timespan from and to details displayed in the form of unix epoch timestamps.

How it works

Before using this endpoint, you can call the List Dimensions endpoint to retrieve all available dimensions that can be used in your query.
Send a GET request to this endpoint with the required metricId and other query parameters.
You receive a response containing the breakdown values for the specified metric, grouped and filtered according to your parameters.
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

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

1	{
2	"success": true,
3	"metadata": {
4	"aggregation": "view_end"
5	},
6	"data": [
7	{
8	"views": 3,
9	"value": 30,
10	"totalWatchTime": 83208,
11	"totalPlayingTime": 57165,
12	"field": "PostmanRuntime"
13	},
14	{
15	"views": 24,
16	"value": 28,
17	"totalWatchTime": 913048,
18	"totalPlayingTime": 2624467,
19	"field": "Chrome"
20	}
21	],
22	"pagination": {
23	"totalRecords": 2,
24	"currentOffset": 1,
25	"offsetCount": 1
26	},
27	"timespan": [
28	1712915263,
29	1713520063
30	]
31	}

$	curl https://api.fastpix.com/v1/data/metrics/views/breakdown \
>	-u "<username>:<password>"