Statistics Resource
 

The Statistics resource helps to obtain usage statistics easily. It allows to retrieve information on your conversion usage, storage usage or bandwidth usage. The statistics data can be queried individually at a "per-day" granularity or you can also query aggregated data (means: the sum of all usage) between a given start and end date. Further, the usage statistics may be either queried as a total usage over your whole user account or be reported "per application" that you have created in your account (note that all usage that you don't link explicitely with one of your custom applications will be counted against a default application - this is e.g. currently the case for all conversion jobs you launch from the web UI).

The following statistics can be queried:

• Conversion: The amount of bytes of video converted/transcoded between the corresponding from/to dates.
• Storage: The amount of bytes of video stored/hosted in the system between the corresponding from/to dates.
• Bandwidth: The number of bytes of video transferred for download/streaming between the corresponding from/to dates.

Obtaining the statistics data
 

GET /stats/{type}

Use either 'conversion', 'storage' or 'bandwidth' as the type of statistics you'd like to retrieve.

Authorization Header

• Bearer token: OAuth 2.0 API access token. 

Parameters 

• format : json or xml. This will override the Request Accept header.
• human : true or false, Causes the response to be in a more structured, human-readably form. Useful e.g. when calling the API through curl or the browser.
  
• view(optional): 'user' or 'application'. Default : 'user'. To get the statistics data either for the overall user account or for per application.
• current_subscription (optional): true or false. If true, returns the statistics information for the time period corredponding to the currently active subscription (= current billing period). If false, returns all stats for the current user without any time/date restrictions. Default: false.
• from_date(optional): A date string indicating from which start date statistics shall be returned. Format : YYYY-MM-DD'T'hh:mm:ss'Z'. Example : 2015-04-19T00:00:00.000Z. 
• to_date(optional): A date string indicating up to which end date statistics data shall be returned. Format : YYYY-MM-DD'T'hh:mm:ss'Z', Example : 2015-04-19T00:00:00.000Z.
• action(optional): Set to 'aggregate' to return a summed up aggreagte over all query records. In the future, futher actions like 'average' etc. may be supported but currently only 'aggregate' is a valid action.

Response

Always returns a statistics "fact" (or "facts" in an array) json that consists of the usage amount (in bytes), corresponding time period (specified by from_date and to_date) and the user id (will be you!) in 'user' view or application id (will be one of your applications) in 'application' view.

Examples

1) Retrieving bandwidth usage for the entire account in the currently active subscription period. Each statistics "record" that is returned corresponds to a one day period (defined by from_date / to_date in the response json):
 

curl -H "Authorization: Bearer um9VmyJKTPGFqpkL_THjGE5rkXqfURDYqQ8MTBVidG3PtwkfABIdx6s_z9WlFl4_j" -H "application/json" "https://api.xvid.com/v1/stats/bandwidth/?format=json&current_subscription=true&human=true"
{
	stats: [
    {
      bandwidth_data: 27159296,
      from_date: 1438300800001,
      to_date: 1438387200000,
      user: {
        id: "54b67486e4b0e8aca492f67d",
        href: "https://api.xvid.com/v1/users/54b67486e4b0e8aca492f67d"
      }
    },
    {
      bandwidth_data: 67674380,
      from_date: 1438473600001,
      to_date: 1438560000000,
      user: {
        id: "54b67486e4b0e8aca492f67d",
        href: "https://api.xvid.com/v1/users/54b67486e4b0e8aca492f67d"
      }
    }
  ]
}

2) Retrieving storage usage for the entire account without any time/date restrictions. Each statistics "record" that is returned corresponds to a one day period (defined by from_date / to_date in the response json):

curl -H "Authorization: Bearer um9VmyJKTPGFqpkL_THjGE5rkXqfURDYqQ8MTBVidG3PtwkfABIdx6s_z9WlFl4_j" "https://api.xvid.com/v1/stats/storage/?format=json"
{
	stats: [
	{
		user: {
			id: "552b874d14eab3a29d1b3d8d",
			href: "https://api.xvid.com/v1/users/552b874d14eab3a29d1b3d8d"
		},
		from_date: 1435795200001,
		to_date: 1435881600000,
		storage_data: 730774413
	},
	{
		user: {
			id: "552b874d14eab3a29d1b3d8d",
			href: "https://api.xvid.com/v1/users/552b874d14eab3a29d1b3d8d"
		},
		from_date: 1435881600001,
		to_date: 1435968000000,
		storage_data: 796400413
	},
	{
		user: {
			id: "552b874d14eab3a29d1b3d8d",
			href: "https://api.xvid.com/v1/users/552b874d14eab3a29d1b3d8d"
		},
		from_date: 1435968000001,
		to_date: 1436054400000,
		storage_data: 796400413
	},
	{
		user: {
			id: "552b874d14eab3a29d1b3d8d",
			href: "https://api.xvid.com/v1/users/552b874d14eab3a29d1b3d8d"
		},
		from_date: 1436054400001,
		to_date: 1436140800000,
		storage_data: 796400413
	},
	{
		user: {
			id: "552b874d14eab3a29d1b3d8d",
			href: "https://api.xvid.com/v1/users/552b874d14eab3a29d1b3d8d"
		},
		from_date: 1436140800001,
		to_date: 1436227200000,
		storage_data: 796400413
	},
	{
		user: {
			id: "552b874d14eab3a29d1b3d8d",
			href: "https://api.xvid.com/v1/users/552b874d14eab3a29d1b3d8d"
		},
		from_date: 1436227200001,
		to_date: 1436313600000,
		storage_data: 796400413
	},
	{
		user: {
			id: "552b874d14eab3a29d1b3d8d",
			href: "https://api.xvid.com/v1/users/552b874d14eab3a29d1b3d8d"
		},
		from_date: 1436313600000,
		to_date: 1436350863827,
		storage_data: 798134295
	}]
}

3) Retrieving information about the conversion usage for the whole user account and aggregating all the usage into a single sum:

curl -H "Authorization: Bearer um9VmyJKTPGFqpkL_THjGE5rkXqfURDYqQ8MTBVidG3PtwkfABIdx6s_z9WlFl4_j" -H "application/json" "https://api.xvid.com/v1/stats/conversion/?action=aggregate"
{
	stats: [{
		from_date: 1434931200001,
		to_date: 1436351027259,
		user: {
			id: "552b874d14eab3a29d1b3d8d",
			href: "https://api.xvid.com/v1/users/552b874d14eab3a29d1b3d8d"
		},
		conversion_data: 130520484
	}]
}

4) Retrieving statistics information per application with the "view=application" query parameter

curl -H "Authorization: Bearer um9VmyJKTPGFqpkL_THjGE5rkXqfURDYqQ8MTBVidG3PtwkfABIdx6s_z9WlFl4_j" -H "application/json" "https://api.xvid.com/v1/stats/conversion/?view=application"
{
	stats: [{
		application: {
			id: "552cae3514ea10cb4d3ac69e"
		},
		from_date: 1434931200001,
		to_date: 1435017600000,
		conversion_data: 64752296
	},
	{
		application: {
			id: "552cae3514ea10cb4d3ac69e"
		},
		from_date: 1435881600001,
		to_date: 1435968000000,
		conversion_data: 64752296
	},
	{
		application: {
			id: "552cae3514ea10cb4d3ac69e"
		},
		from_date: 1436313600000,
		to_date: 1436351188562,
		conversion_data: 1015892
	}]
}

AutoGraph-specific Bandwidth Statistics

GET /stats/bandwidth/tags/SOME_AUTOGRAPH_TAG

Bandwidth statistics for a particular user identified by AutoGraph Tag.

Authorization Header

• Bearer token: OAuth 2.0 API access token. 

Parameters 

• format : json or xml. This will override the Request Accept header.
• human : true or false, Causes the response to be in a more structured, human-readably form. Useful e.g. when calling the API through curl or the browser.
  
• application_id: Restrict the results in the response to just the application indicated by the application id.
• from_date(optional): A timestamp indicating from which start date statistics shall be returned. Timestamp format is javascript, so must be provided in milliseconds (and not seconds). 
• to_date(optional): A timestamp indicating up to which end date statistics data shall be returned. Timestamp format is javascript, so must be provided in milliseconds (and not seconds).
• action(optional): Set to 'aggregate' to return a sum of the total number of bytes that the user transferred instead of the individual per-hour slices. In the future, futher actions like 'average' etc. may be supported but currently only 'aggregate' is a valid action.

Response

Returns information about the amount of bytes the user with the given AutoGraph Tag transferred within one hour time slices during the time period specified by "from_date" and "to_date" parameters.

Example

curl -H "Authorization: Bearer um9VmyJKTPGFqpkL_THjGE5rkXqfURDYqQ8MTBVidG3PtwkfABIdx6s_z9WlFl4_j" -H "application/json" "https://api.xvid.com/v1/stats/bandwidth/tags/User1?from_date=1599742800000&format=json&human=true"
{
	stats: [
    {
      "tag": "User1",
      "application": {
        "id": "51702847f4b12082e3670811",
        "href": "https://api.xvid.com/v1/applications/51702847f4b12082e3670811"
      },
      "from_date": 1599742800000,
      "to_date": 1599746400000,
      "bandwidth_data": 4100040407
    }
  ]
}

GET /stats/bandwidth/tags/

Bandwidth statistics showing the Top 10 users with the highest bandwidth usage.

Authorization Header

• Bearer token: OAuth 2.0 API access token. 

Parameters 

• format : json or xml. This will override the Request Accept header.
• human : true or false, Causes the response to be in a more structured, human-readably form. Useful e.g. when calling the API through curl or the browser.
  
• application_id: Restrict the results in the response to just the application indicated by the application id.
• from_date(optional): A timestamp indicating from which start date statistics shall be returned. Timestamp format is javascript, so must be provided in milliseconds (and not seconds). 
• to_date(optional): A timestamp indicating from which start date statistics shall be returned. Timestamp format is javascript, so must be provided in milliseconds (and not seconds).

Response

Returns information about the 10 users (or rather their AutoGraph Tags) which had the highest bandwidth usage during the time period specified by "from_date" and "to_date" parameters.

Example

curl -H "Authorization: Bearer um9VmyJKTPGFqpkL_THjGE5rkXqfURDYqQ8MTBVidG3PtwkfABIdx6s_z9WlFl4_j" -H "application/json" "https://api.xvid.com/v1/stats/bandwidth/tags/?from_date=1599742800000&format=json&human=true"
{
	stats: [
    {
      "top_tags": [
        {
          "tag": "User1",
          "bandwidth_data": 4100040407
        },
        {
          "tag": "User2",
          "bandwidth_data": 2994481921
        },
        {
          "tag": "User3",
          "bandwidth_data": 1189246675
        },
        {
          "tag": "User4",
          "bandwidth_data": 1122763867
        },
        {
          "tag": "User5",
          "bandwidth_data": 638298762
        },
        {
          "tag": "User6",
          "bandwidth_data": 561405451
        },
        {
          "tag": "User7",
          "bandwidth_data": 355603954
        },
        {
          "tag": "User8",
          "bandwidth_data": 305581725
        },
        {
          "tag": "User9",
          "bandwidth_data": 259249171
        },
        {
          "tag": "User10",
          "bandwidth_data": 250876974
        }
      ],
      "application": {
        "id": "51702847f4b12082e3670811",
        "href": "https://api.xvid.com/v1/applications/51702847f4b12082e3670811"
      },
      "from_date": 1599742800000,
      "to_date": 1599746400000
    }
  ]
}