All Products
Search

This Product

    ApsaraVideo VOD:DescribeVodPlayerMetricData

    Document Center

    ApsaraVideo VOD:DescribeVodPlayerMetricData

    Last Updated:Jul 21, 2026

    Queries player metric data.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    vod:DescribeVodPlayerMetricData

    none

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    AppId

    string

    Yes

    The application ID.

    app-1000000
    StartTime

    string

    Yes

    The start time of the query. Format: yyyy-mm-ddthh:mm:ssz (UTC).

    Note

    • Supports querying playback data history for the past year.

    • The time range for a single query cannot exceed 31 days.

    • The time interval is left-closed and right-open [StartTime, EndTime).

    2025-06-24T00:55:06Z
    EndTime

    string

    Yes

    The end time of the query. Format: yyyy-mm-ddthh:mm:ssz (UTC).

    2025-06-05T15:59:59Z
    Interval

    string

    Yes

    The time granularity for querying data. Valid values: 5m, 1h, and 1d. The supported time granularity depends on the time span between StartTime and EndTime:

    • Within 3 days: 5m, 1h, and 1d.

    • 4 to 7 days: 1h and 1d.

    • More than 7 days: 1d.

    1d
    TerminalType

    string

    Yes

    The terminal type. Valid values:

    • web: web.

    • mobile: native.

    web
    Filters

    string

    No

    The metric dimension filters. A dimension consists of a dimension type (Field), an operator (Op), and a dimension value.

    Note

    • A maximum of three dimensions can be specified.

    • When the Metrics parameter includes the following four metrics, Filters do not take effect: Uv (playback users), AvgPerVv (average plays per user), AvgPerPlayDuration (average play duration per user), and AvgPerCompletionVv (average completion plays per user).

    • For provinces and countries, pass the regionCode.

    • Separate multiple values with #_#.

    Valid values for dimension type (Field):

    • SdkVersion: SDK version.

    • AppVersion: app version.

    • Codec: codec.

    • VideoType: video format.

    • Network: network type.

    • Country: country.

    • Isp: ISP.

    • VideoDefinition: resolution.

    • Domain: domain name.

    • Province: province.

    • IsHw: whether hardware decoding is used.

    • ErrorCode: error code.

    Valid values for operator (Op): = (equal to), > (greater than), < (less than), and != (not equal to).

    Note

    • SdkVersion and VideoDefinition support all four operators. Other metrics support only = (equal to) and != (not equal to).

    Retrieve dimension values by calling DescribeVodPlayerDimensionData.

    [ { "Field": "codec", "Op": "=", "Value": "h265#_#h264" }, { "Field": "os", "Op": "=", "Value": "Android#_#iOS" } ]
    Metrics

    string

    Yes

    The metric types. You can select multiple metrics (up to 3).

    Note

    • Percentage data is returned in decimal form.

    Quality of Service (QoS) metrics:

    • Vv: play count.

    • RealVv: actual play count.

    • FirstFrame: first frame time.

    • SecondPlayRate: instant play rate.

    • SlowPlayRate: slow play rate.

    • StuckCountRate: stuttering rate by count.

    • SeekDuration: seek duration.

    • StuckDuration100s: stuttering duration per 100 seconds.

    • StuckCount100s: stuttering count per 100 seconds.

    • PlayFailRate: play failure rate.

    • SeedFailRate: non-play rate.

    • AvgPlayBitrate: average playback bitrate.

    • AvgStartBitrate: average start bitrate.

    • ErrorCount100s: error count per 100 seconds.

    Quality of Experience (QoE) metrics:

    • Uv: playback users.

    • AvgPerVv: average plays per user.

    • AvgVideoDuration: average video duration.

    • AvgPerPlayDuration: average play duration per user.

    • AvgPerCompletionVv: average completion plays per user.

    • CompletionVv: completion count.

    • CompletionRate: completion rate.

    • AvgPlayDuration: average play duration.

    • JumpRate5s: 5-second bounce rate.

    Vv,Uv,AvgPerVv
    Top

    integer

    No

    Returns data for the top N items ranked by play count. If this parameter is not specified, data for all dimensions is returned.

    5
    PageNumber

    integer

    No

    The page number. Default value: 1.

    1
    PageSize

    integer

    No

    The number of entries per page. Default value: 5000. Maximum value: 5000.

    5000
    Language

    string

    No

    The language of the response. Valid values:

    • zh (default): Simplified Chinese.

    • en: English.

    zh
    Os

    string

    No

    The operating system of the player. Specify this parameter to perform a filtered query for playback data of a specific operating system. Valid values: Android, iOS, Harmony, Windows, MacOS, and Linux. The available values vary by terminal type:

    • native: Android, iOS, Harmony.

    • web: Android, iOS, Harmony, Windows, MacOs, Linux.

    Separate multiple values with #_#.

    Android、iOS、Windows

    Response elements

    Element

    Type

    Description

    Example

    object

    Schema of Response

    RequestId

    string

    Id of the request

    25818875-5F78-4A*****F6-D7393642CA58
    PageNumber

    integer

    The current page number.

    1
    PageSize

    integer

    The page size.

    5000
    TotalCnt

    integer

    The total number of data points.

    500
    DataList

    array<object>

    The list of returned data.

    object

    TimeStamp

    string

    The timestamp of the data. Format: yyyy-mm-ddthh:mm:ssz (UTC).

    2025-06-24T00:55:06Z

    Dimension

    string

    The dimension.

    H265_MP4_WIFI
    Uv

    number

    The number of playback users.

    500
    Vv

    number

    The play count.

    800
    RealVv

    number

    The actual play count.

    1000
    FirstFrame

    number

    The first frame time, in milliseconds (ms).

    100
    SecondPlayRate

    number

    The instant play rate.

    0.8
    SlowPlayRate

    number

    The slow play rate.

    0.2
    StuckCountRate

    number

    The stuttering rate by count.

    0.1
    SeekDuration

    number

    The seek duration, in milliseconds (ms).

    100
    StuckDuration100s

    number

    The stuttering duration per 100 seconds, in milliseconds (ms).

    200
    PlayFailRate

    number

    The play failure rate.

    0.2
    SeedFailRate

    number

    The non-play rate.

    0.01
    AvgPlayBitrate

    number

    The average playback bitrate, in bps.

    100
    AvgStartBitrate

    number

    The average start bitrate, in bps.

    100
    ErrorCount100s

    number

    The error count per 100 seconds.

    1
    AvgPerVv

    number

    The average plays per user.

    10
    AvgVideoDuration

    number

    The average video duration, in milliseconds (ms).

    100000
    AvgPerPlayDuration

    number

    The average play duration per user, in milliseconds (ms).

    100000
    AvgPerCompletionVv

    number

    The average completion plays per user.

    2
    CompletionVv

    number

    The completion count.

    500
    CompletionRate

    number

    The completion rate.

    0.8
    AvgPlayDuration

    number

    The average play duration, in milliseconds (ms).

    100000

    JumpRate5s

    number

    The 5-second bounce rate.

    0.1
    TotalPlayDuration

    number

    The total play duration, in milliseconds (ms).

    100000
    StuckCount100s

    string

    The stuttering count per 100 seconds.

    2
    Extend

    object

    The extended information.

    ActualStartTime

    string

    The earliest time with data points within the specified time range. Format: yyyy-mm-ddthh:mm:ssz (UTC).

    2025-06-24T00:55:06Z
    ActualEndTime

    string

    The latest time with data points within the specified time range. Format: yyyy-mm-ddthh:mm:ssz (UTC).

    2025-06-05T15:59:59Z
    IntervalSeconds

    integer

    The time granularity of the queried data, in seconds (s).

    3600

    Examples

    Success response

    JSON format

    {
  "RequestId": "25818875-5F78-4A*****F6-D7393642CA58",
  "PageNumber": 1,
  "PageSize": 5000,
  "TotalCnt": 500,
  "DataList": [
    {
      "TimeStamp": "2025-06-24T00:55:06Z\n",
      "Dimension": "H265_MP4_WIFI",
      "Uv": 500,
      "Vv": 800,
      "RealVv": 1000,
      "FirstFrame": 100,
      "SecondPlayRate": 0.8,
      "SlowPlayRate": 0.2,
      "StuckCountRate": 0.1,
      "SeekDuration": 100,
      "StuckDuration100s": 200,
      "PlayFailRate": 0.2,
      "SeedFailRate": 0.01,
      "AvgPlayBitrate": 100,
      "AvgStartBitrate": 100,
      "ErrorCount100s": 1,
      "AvgPerVv": 10,
      "AvgVideoDuration": 100000,
      "AvgPerPlayDuration": 100000,
      "AvgPerCompletionVv": 2,
      "CompletionVv": 500,
      "CompletionRate": 0.8,
      "AvgPlayDuration": 100000,
      "JumpRate5s": 0.1,
      "TotalPlayDuration": 100000,
      "StuckCount100s": "2"
    }
  ],
  "Extend": {
    "ActualStartTime": "2025-06-24T00:55:06Z",
    "ActualEndTime": "2025-06-05T15:59:59Z",
    "IntervalSeconds": 3600
  }
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 Meter.ParamError Param Error:%s,Please Check Again. One or more parameters are invalid.
    500 Meter.ServerInternalError The Request Processing Has Failed Due To Some Unknown Error. An internal error occurred.
    500 Meter.DataSourceQueryError Data Source Error:%s,Please Try Again. An internal data source error occurred.
    403 Meter.AuthError Authentication Failed,Please Try Again. You do not have permissions to perform this operation.
    502 Meter.ReadyTsError Get ReadyTs Failed,Please Try Again. The data is not prepared.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.