Analytics and billing - Kinescope help center

Billing

Usage

GET https://api.kinescope.io/v1/billing/usage

Returns usage statistics for the given time range, grouped as requested. Useful for billing and capacity planning.

Our API returns resource consumption on a per project basis for better granularity, you can aggregate total on your side.

If necessary, you can specify project_id as a GET parameter to filter the results

Product types are: - CDN (bytes) - Encoding (min) - Storage (bytes)

Responses

{
 "data": [
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 85456358,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 65114706,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 29962188,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 904705,
   "product": "cdn"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 0,
   "product": "encoding"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 689510432,
   "product": "live_traffic"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 69567273960,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 14996434987,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 34667181,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 130330116051,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 4172549388,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 16632753546,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 556115506,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 601660745,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 10406392731,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-01T00:00:00Z",
   "usage": 6286301827,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 37429638,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 97450301,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 560037,
   "product": "cdn"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 0,
   "product": "encoding"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 882356207,
   "product": "live_traffic"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 69567273960,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 14996434987,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 34667181,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 130330116051,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 4172549388,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 16632753546,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 556115506,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 601660745,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 10406392731,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-02T00:00:00Z",
   "usage": 6286301827,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 12476546,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 36428908,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 618293,
   "product": "cdn"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 0,
   "product": "encoding"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 750185902,
   "product": "live_traffic"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 69567273960,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 14996434987,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 34667181,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 130330116051,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 4172549388,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 16632753546,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 556115506,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 601660745,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 10406392731,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-03T00:00:00Z",
   "usage": 6286301827,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 42455143,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 48519990,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 89726,
   "product": "cdn"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 0,
   "product": "encoding"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 877485751,
   "product": "live_traffic"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 69567273960,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 14996434987,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 34667181,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 130330116051,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 4172549388,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 16632753546,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 556115506,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 601660745,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 10406392731,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-04T00:00:00Z",
   "usage": 6286301827,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 114946977,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 45670557,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 79114792,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 1443490,
   "product": "cdn"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 0,
   "product": "encoding"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 802691136,
   "product": "live_traffic"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 69567273960,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 14996434987,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 34667181,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 130330116051,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 4172549388,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 16632753546,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 556115506,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 601660745,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 10406392731,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-05T00:00:00Z",
   "usage": 6286301827,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 7342272,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 24953092,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 38352386,
   "product": "cdn",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 511222,
   "product": "cdn"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 0,
   "product": "encoding"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 679400275,
   "product": "live_traffic"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 69567273960,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 14996434987,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 34667181,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 130330116051,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage": 4172549388,
   "product": "storage",
   "project_id": "<UUID>"
  },
  {
   "date": "2024-01-06T00:00:00Z",
   "usage":
// … truncated

Analytics

Overview

GET https://api.kinescope.io/v1/analytics/overview

Returns high-level playback statistics for the given period: totals for the whole period (data.total), the same metrics broken down by time buckets (data.timeline), and top lists by OS, device, browser, country, and city (data.top). Pass video_id to get statistics for a single video instead of the whole workspace.

Query parameters

Parameter	Description
`from`	Required. Start of the period — `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`.
`to`	Required. End of the period, same formats as `from`.
`group_time`	Optional. Time bucket for `data.timeline` points: `minute` (`1m`), `hour`, `day` (default), `week`, `month`, or an interval like `15m`.
`video_id`	Optional. ID of the video to get statistics for. Without it — the whole workspace.
`external_id`	Optional. External ID of the video, if one was assigned to it.

Response fields: data.total, data.timeline[]

Field	Description
`views`	Number of views.
`unique_views`	Number of unique viewers.
`player_loads`	Number of player loads.
`duration`	Total playback duration.
`watch_time`	Total watch time.
`online`	Number of viewers online.
`date`	Start of the time bucket. Not used in `data.total` (`0001-01-01T00:00:00Z`).

Response fields: data.top lists

Field	Description
`name`	Value: OS, device, browser, country, or city.
`code`	Two-letter country code (only in `countries`).
`views`	Number of views.
`player_loads`	Number of player loads.
`unique_views`	Number of unique viewers.

Responses

{
  "meta": {
    "time": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T00:00:00Z",
      "timezone": "Europe/Moscow"
    }
  },
  "data": {
    "total": {
      "views": 15432,
      "duration": 5123400,
      "watch_time": 4820153,
      "player_loads": 18902,
      "date": "0001-01-01T00:00:00Z",
      "unique_views": 11097,
      "online": 12
    },
    "timeline": [
      {
        "views": 541,
        "duration": 178320,
        "watch_time": 167415,
        "player_loads": 662,
        "date": "2024-01-10T21:00:00Z",
        "unique_views": 412,
        "online": 12
      },
      {
        "views": 488,
        "duration": 160910,
        "watch_time": 151002,
        "player_loads": 594,
        "date": "2024-01-11T21:00:00Z",
        "unique_views": 389,
        "online": 9
      }
    ],
    "top": {
      "oses": [
        {
          "name": "Android",
          "views": 8123,
          "player_loads": 9904,
          "unique_views": 6011
        },
        {
          "name": "iOS",
          "views": 5304,
          "player_loads": 6612,
          "unique_views": 3980
        }
      ],
      "devices": [
        {
          "name": "desktop",
          "views": 8204,
          "player_loads": 10012,
          "unique_views": 6002
        },
        {
          "name": "mobile",
          "views": 6011,
          "player_loads": 7210,
          "unique_views": 4410
        }
      ],
      "browsers": [
        {
          "name": "Chrome",
          "views": 7611,
          "player_loads": 9200,
          "unique_views": 5590
        },
        {
          "name": "Safari",
          "views": 4310,
          "player_loads": 5544,
          "unique_views": 3120
        }
      ],
      "countries": [
        {
          "name": "Russia",
          "code": "RU",
          "views": 11230,
          "player_loads": 13660,
          "unique_views": 8305
        },
        {
          "name": "Brazil",
          "code": "BR",
          "views": 2044,
          "player_loads": 2610,
          "unique_views": 1509
        }
      ],
      "cities": [
        {
          "name": "Moscow",
          "views": 4870,
          "player_loads": 5810,
          "unique_views": 3560
        },
        {
          "name": "São Paulo",
          "views": 1140,
          "player_loads": 1470,
          "unique_views": 830
        }
      ]
    }
  }
}

Custom

GET https://api.kinescope.io/v1/analytics

Returns a custom analytics slice: you choose which fields each row contains (fields), how rows are grouped in time and by entities (group, group_entities), and the sort order (order). Each row contains the requested fields.

Query parameters

Parameter	Description
`from`	Required. Start of the period — `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`.
`to`	Required. End of the period, same formats as `from`.
`fields`	Needed to get data rows: the fields each row contains — see the table below. Repeat the parameter to request several: `fields=view&fields=play`.
`group`	Optional. Time bucket for `date` in each row: `minute` (`1m`), `hour`, `day` (default), `week`, `month`, or an interval like `15m`.
`group_entities`	Optional. Dimensions to group rows by, e.g. `group_entities=video_id`. Repeat the parameter to group by several dimensions.
`limit`	Optional. Maximum number of rows.
`order`	Optional. Sort as `field.asc` or `field.desc`; several — comma-separated: `order=view.desc,date.asc`. Default: `date.desc`. Sortable fields are marked yes in the Sorting column of the table below; `date` can also be sorted, but only together with `group`. A field without a direction means `asc`.
`<dimension>=<value>`	Optional filter by any dimension from the table below: `video_id`, `external_id`, `project_id`, `folder_id`, `type`, `device`, `os`, `browser`, `city`, `country_code`. Repeat the parameter to pass several values: `country_code=US&country_code=DE`.

Fields (fields)

Field	Type	Sorting	Description
`video_id`	dimension	yes	Video ID.
`external_id`	dimension	yes	External ID of the video.
`project_id`	dimension	yes	Project ID.
`folder_id`	dimension	yes	Folder ID.
`type`	dimension	no	Content type: `vod` or `live`.
`device`	dimension	yes	Device type: `desktop`, `mobile`, `tablet`, `tv`.
`os`	dimension	yes	Operating system.
`browser`	dimension	yes	Browser.
`city`	dimension	yes	City.
`country_code`	dimension	yes	Country code.
`view`	metric	yes	Number of views.
`unique_view`	metric	no	Number of unique viewers.
`play`	metric	yes	Number of playback starts.
`pause`	metric	yes	Number of pauses.
`seek`	metric	yes	Number of seeks.
`replay`	metric	yes	Number of replays.
`end`	metric	no	Number of views watched to the end.
`rate`	metric	no	Number of playback speed changes.
`player_init`	metric	yes	Number of player initializations.
`player_load`	metric	yes	Number of player loads.
`watch_time`	metric	no	Total watch time.
`duration`	metric	no	Maximum video duration among the videos in the row.
`buffering_time`	metric	yes	Total buffering time.
`buffering_count`	metric	yes	Number of buffering events.
`change_quality`	metric	no	Number of quality switches, manual and automatic.
`heatmap`	metric	no	Engagement map: for each second of the video, the number of viewers who watched it. Returned as an object `{"<second>": <viewers>}`.

When folder_id or project_id is requested, the response also includes folder_name / project_name — the names of the folder or project.

Responses

{
  "meta": {
    "order": {
      "view": "desc"
    },
    "time": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T00:00:00Z",
      "timezone": "Europe/Moscow"
    },
    "group_entities": [
      "video_id"
    ]
  },
  "data": [
    {
      "video_id": "4iUMUmb63dLAvnbsMRkSUX",
      "date": "2024-01-10T21:00:00Z",
      "view": 245,
      "unique_view": 187,
      "player_load": 312,
      "watch_time": 45210
    },
    {
      "video_id": "4iUMUmb63dLAvnbsMRkSUX",
      "date": "2024-01-11T21:00:00Z",
      "view": 231,
      "unique_view": 175,
      "player_load": 298,
      "watch_time": 43180
    },
    {
      "video_id": "2nQqTmb63dLAvnbsMRkSUZ",
      "date": "2024-01-10T21:00:00Z",
      "view": 198,
      "unique_view": 154,
      "player_load": 244,
      "watch_time": 39750
    }
  ]
}

curl -X GET \
  'https://api.kinescope.io/v1/analytics?from=2024-01-01&to=2024-01-31&group=day&group_entities=video_id&fields=video_id&fields=view&fields=unique_view&fields=player_load&fields=watch_time&order=view.desc&limit=10' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Video heatmap

GET https://api.kinescope.io/v1/analytics/video/:video_id/heatmap

Returns the video engagement heatmap — the same engagement graph you see in the dashboard. For each second of the video, the API returns the share of viewers who watched that second. Values range from 0 to 1, where 1 means every viewer watched that moment.

Responses

{
  "meta": {
    "time": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T00:00:00Z",
      "timezone": "Europe/Moscow"
    }
  },
  "data": {
    "points": [
      {
        "value": 1,
        "second": 0
      },
      {
        "value": 0.98,
        "second": 1
      },
      {
        "value": 0.95,
        "second": 2
      },
      {
        "value": 0.45,
        "second": 300
      }
    ]
  }
}

Video referrers

GET https://api.kinescope.io/v1/analytics/video/:video_id/referrer

Returns the pages that referred viewers to the video (traffic sources) with the number of views and player loads for each source. Pass format=csv or format=xlsx to download the report as a file; without the parameter the response is JSON.

Responses

{
  "meta": {
    "time": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T00:00:00Z",
      "timezone": "Europe/Moscow"
    }
  },
  "data": [
    {
      "url": "https://example.com/lesson-1",
      "views": 245,
      "player_loads": 312,
      "video_id": "4iUMUmb63dLAvnbsMRkSUX"
    },
    {
      "url": "https://example.org/courses/",
      "views": 187,
      "player_loads": 230,
      "video_id": "4iUMUmb63dLAvnbsMRkSUX"
    }
  ]
}

Event online viewers

GET https://api.kinescope.io/v1/analytics/events/:event_id/online

Returns the concurrent-viewers timeline for a live event stream: one point per group_time bucket. Peak concurrent viewers is the maximum of timeline[].online.

stream_id is optional. If omitted, the API uses the event's current stream (pending or on-air; for a one-time event also a finished stream). If the event has no current stream, stream_id is null and timeline is an empty array.

from and to are optional. By default the period is the stream itself: started_at to finished_at, or to now if the stream is still live.

Path parameters

Parameter	Description
`event_id`	Live event ID.

Query parameters

Parameter	Description
`stream_id`	Optional. Stream ID. Must belong to the event. Without it — the event's current stream. For a `pending` stream the timeline is empty.
`from`	Optional. Start of the period — `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`. Default: stream start.
`to`	Optional. End of the period, same formats as `from`. Default: stream end, or now if the stream is live.
`group_time`	Optional. Time bucket for `timeline` points: `1m` (default), `hour`, `day`, `week`, `month`, or an interval like `5m`.

Response fields

Field	Description
`stream_id`	Stream the timeline is built for. `null` if the event has no current stream.
`timeline`	Points for each `group_time` bucket. Empty array when there is no data or the stream is `pending`.
`timeline[].date`	Start of the bucket (RFC3339).
`timeline[].online`	Concurrent viewers in the bucket.

Responses

{
  "meta": {
    "time": {
      "from": "2024-01-01T18:40:00Z",
      "to": "2024-01-01T19:10:00Z",
      "timezone": "Europe/Moscow"
    }
  },
  "data": {
    "stream_id": "60e64b83-21c4-4502-a138-a06635f8210e",
    "timeline": [
      {
        "date": "2024-01-01T18:40:00Z",
        "online": 1204
      },
      {
        "date": "2024-01-01T18:41:00Z",
        "online": 1487
      },
      {
        "date": "2024-01-01T18:42:00Z",
        "online": 1523
      }
    ]
  }
}