> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# List breakdown values

GET https://api.fastpix.com/v1/data/metrics/{metricId}/breakdown

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

Reference: https://fastpix.com/docs/video-data-api/metrics/list-breakdown-values

## Authentication

- `Authorization` header (basic auth, required) — 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

## Request

### Path parameters

- `metricId` (enum, required) — Pass metric Id
  - Allowed values: `views`, `unique_viewers`, `playing_time`, `quality_of_experience_score`, `playback_score`, `playback_failure_percentage`, `exit_before_video_start`, `video_startup_failure_percentage`, `startup_score`, `video_startup_time`, `player_startup_time`, `page_load_time`, `total_startup_time`, `live_stream_latency`, `average_bitrate`, `buffer_count`, `render_quality_score`, `avg_upscaling`, `avg_downscaling`, `max_upscaling`, `max_downscaling`, `jump_latency`, `stability_score`, `buffer_ratio`, `buffer_frequency`, `buffer_fill`

### Query parameters

- `timespan[]` (enum, optional) — 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`
  - Allowed values: `60:minutes`, `6:hours`, `24:hours`, `3:days`, `7:days`, `30:days`
- `filterby[]` (string, optional) — 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 ]
- `limit` (integer, optional, default: 10) — Pass the limit to display only the rows specified by the value.
- `offset` (integer, optional, default: 1) — Pass the offset value to indicate the page number.
- `groupBy` (string, optional) — 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".]
- `orderBy` (string, optional, default: views) — Pass this value to order the metrics list by.
- `sortOrder` (enum, optional, default: asc) — The order direction to sort the metrics list by.
  - Allowed values: `asc`, `desc`
- `measurement` (string, optional, default: avg) — The measurement for the given metrics. Possible Values : [95th, median, avg, count or sum]

## Response

### 200

Get filter/ dimension value details by dimension name.

- `success` (boolean, optional) — Shows the request status. Returns true for success and false for failure.
- `metadata` (MetricsmetadataDetails, optional) — Retrieves breakdown values for a specified metric and timespan
- `data` (list of MetricsBreakdownDetailsItems, optional) — Retrieves breakdown values for a specified metric and timespan
- `pagination` (DataPagination, optional) — Pagination organizes content into pages for better readability and navigation.
- `timespan` (list of integer, optional) — The timespan from and to details displayed in the form of unix epoch timestamps.

## Types

### MetricsmetadataDetails

Retrieves breakdown values for a specified metric and timespan

- `aggregation` (string, optional) — defines the field or dimension on which the aggregation is to be applied.

### MetricsBreakdownDetailsItems

- `views` (integer, optional, nullable) — Total count of view sessions for a paricular video content.
- `value` (double, optional, nullable) — The specific metric value calculated based on the applied filters.
- `totalWatchTime` (integer, optional, nullable) — Total time watched across all views, represented in milliseconds.
- `totalPlayingTime` (integer, optional, nullable) — Total time spent playing the video, represented in milliseconds.
- `field` (string, optional, nullable) — the value of dimension or filter value on which the aggregation is to be applied.

### DataPagination

Pagination organizes content into pages for better readability and navigation.

- `totalRecords` (integer, optional) — The total number of records retrieved within the timespan.
- `currentOffset` (integer, optional) — The current offset value. Default: 1
- `offsetCount` (integer, optional) — The total number of offsets based on limit.

## Examples

**Response**

```json
{
  "success": true,
  "metadata": {
    "aggregation": "view_end"
  },
  "data": [
    {
      "views": 3,
      "value": 30,
      "totalWatchTime": 83208,
      "totalPlayingTime": 57165,
      "field": "PostmanRuntime"
    },
    {
      "views": 24,
      "value": 28,
      "totalWatchTime": 913048,
      "totalPlayingTime": 2624467,
      "field": "Chrome"
    }
  ],
  "pagination": {
    "totalRecords": 2,
    "currentOffset": 1,
    "offsetCount": 1
  },
  "timespan": [
    1712915263,
    1713520063
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.fastpix.com/v1/data/metrics/views/breakdown"

response = requests.get(url, auth=("<username>", "<password>"))

print(response.json())
```

```javascript
const url = 'https://api.fastpix.com/v1/data/metrics/views/breakdown';
const credentials = btoa("<username>:<password>");

const options = {method: 'GET', headers: {Authorization: `Basic ${credentials}`}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fastpix.com/v1/data/metrics/views/breakdown"

	req, _ := http.NewRequest("GET", url, nil)

	req.SetBasicAuth("<username>", "<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.fastpix.com/v1/data/metrics/views/breakdown")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request.basic_auth("<username>", "<password>")

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.fastpix.com/v1/data/metrics/views/breakdown")
  .basicAuth("<username>", "<password>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.fastpix.com/v1/data/metrics/views/breakdown', [
  'headers' => [
  ],
    'auth' => ['<username>', '<password>'],
]);

echo $response->getBody();
```

```csharp
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.fastpix.com/v1/data/metrics/views/breakdown");
client.Authenticator = new HttpBasicAuthenticator("<username>", "<password>");
var request = new RestRequest(Method.GET);

IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let credentials = Data("<username>:<password>".utf8).base64EncodedString()

let headers = ["Authorization": "Basic \(credentials)"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.fastpix.com/v1/data/metrics/views/breakdown")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```