Stats API

Learn how to access your stats via our API.

Ever looked at your Wistia heatmaps and wished you could show them to other people with ease? Ever looked at your Wistia heatmaps and wished that they were built out of purple cats instead of red, yellow, and green bars?

Want to figure out which of your Wistia videos your users have already viewed and recommend them ones they haven't so they don't get bored?

Want to make sure you purposely recommend the same videos repeatedly until they're annoyed enough to convert?

Look no further, developers: the Wistia Stats API has you covered.

Account

Account: Show

The stats API allows you to retrieve some account-wide information. Don't buy a nice car to overcompensate; instead, show off how many hours of your video have been played! Or, celebrate when you reach a certain landmark.

The Request

In order to tell Wistia that you want stats for your account, issue a GET request to the following URL:

GET https://api.wistia.com/v1/stats/account.json

The Response

FieldDescription
load_countThe total number of times all of the videos from this account have been loaded.
play_countThe total number of times all of the videos from this account have been played.
hours_watchedThe total amount of time spent watching all of the videos in this account.

Example JSON Response

Status: 200 OK

  {
    "load_count": 1000,
    "play_count": 400,
    "hours_watched": 21.9
  }

Project

Project: Show

The stats API allows you to retrieve information about all of the videos in a particular project. We know you like it when we let you get specific.

The Request

In order to retrieve stats for a project, issue a GET request to the following URL (you can find the Project ID in the URL for that project):

GET https://api.wistia.com/v1/stats/projects/[project-id].json

The Response

The response will come back as a single object representing the stats for this project.

FieldDescription
load_countThe total number of times the videos in this project have been loaded.
play_countThe total number of times the videos in this project have been played.
hours_watchedThe total time spent viewing the videos in this project.
number_of_videosThe total number of videos in this project.

Example JSON Response

Status: 200 OK

{
  "load_count": 5498,
  "play_count": 3942,
  "hours_watched": 59.8,
  "number_of_videos": 8,
}

Media

Media: Show

The Wistia stats API can be used to retrieve stats for any given video. Ever wanted to entice that special someone (or those hundreds of special someones viewing your page) to watch your video? Win their heart by displaying impressive data like your engagement rate. Or, give away a puppy to the thousandth viewer of your video. We heard you can 3D print those now.

The Request

In order to get stats for a video, issue a GET request to the following URL (you can find the Media ID in the URL for that media):

GET https://api.wistia.com/v1/stats/medias/[media-id].json

The Response

FieldDescription
load_countThe total number of times this video has been loaded.
play_countThe total number of times this video has been played.
play_rateThe percentage of visitors who clicked play (between 0 and 1).
hours_watchedThe total time spent watching this video.
engagementThe average percentage of the video that gets viewed (between 0 and 1).
visitorsThe total number of unique people that have loaded this video.
actionsThe stats for this video's Turnstile, Annotation, and Call to Action.

Example JSON Response

Status: 200 OK

{
  "load_count": 100,
  "play_count": 80,
  "play_rate": 0.54,
  "hours_watched": 21.9,
  "engagement": 0.89,
  "visitors": 94,
  "actions": [{ "type": "Call to Action", "action_count": 24, "impression_count": 84, "rate": 0.286 }]
}

Media: Engagement

Using the stats API, you can retrieve the data used to construct the engagement graphs at the top of the stats page for any video in Wistia.

The Request

GET https://api.wistia.com/v1/stats/medias/[media-id]/engagement.json

Parameters

This method does not take any parameters besides the media-id that is already specified in the URL.

The Response

The response will come back as a single object that represents the main engagement data:

FieldDescription
engagementThe percentage of the video that was viewed, averaged across all viewing sessions.
engagement_dataAn array which can be used as the data source for creating an engagement graph. Normally, each cell in the array represents how many times 1 second of the video has been viewed. However, for longer form content (over 1000 seconds), the array will be scaled down to 1000 items, with each item representing more than 1 second of playback.
rewatch_dataAn array which can be used for creating the rewatch block on an engagement graph. Normally, each cell in the array represents how many times 1 second of the video has been viewed. However, for longer form content (over 1000 seconds), the array will be scaled down to 1000 items, with each item representing more than 1 second of playback.

Example JSON Response

Status: 200 OK

{
  "engagement": 0.75,
  "engagement_data": [ 154, 152, 152, 151, 148, ... ],
  "rewatch_data": [ 13, 17, 19, 19, 15, ... ]
}

Visitors

Visitors: List

This method allows you to retrieve a list of visitors that have watched videos in your account.

The Request

GET https://api.wistia.com/v1/stats/visitors.json

Parameters

ParameterDescription
pageThe page of results that you want, based on the per_page parameter.
per_pageThe maximum number of results to return. This value is capped at 100.
filterThis parameter is optional and can take one of three values: 'has_name' or 'has_email' or 'identified_by_email_gate'. Without the parameter, all visitors are returned. For the value 'has_name', only named visitors are returned. For the value 'has_email', only visitors with an email address are returned. For the value 'identified_by_email_gate', only visitors who have entered their email in a video email gate are returned.
searchIf this parameter is specified, only visitors whose name or email address contains the exact given value will be returned.

The Response

The response will be an array of objects. Each object represents a single visitor with the following fields:

Fields

FieldDescription
visitor_keyThis is a unique identifier for the visitor.
created_atWhen the visitor was created - i.e. when they first loaded a video in the account.
last_active_atThe last time the visitor played a video.
last_event_keyThe event key which can be used to retrieve the information about what happened when they last played a video.
load_countThe total number of videos that have been loaded (but not necessarily viewed) by this visitor.
play_countThe total number of videos that have been viewed by this visitor.
identifying_event_keyThe key of the event that was used to identify this visitor. Some examples: the first turnstile this visitor entered or the first load event that was tagged with this visitor info via wemail.
visitor_identityAn object with 3 fields (name, email, and org) that represents the available identity info for this visitor.
user_agent_detailsAn object with 4 fields: browser (e.g. 'Chrome'), browser_version (e.g. '46'), platform (e.g. 'mac'), and mobile (boolean value stating whether the visitor was on their mobile phone.)

Example JSON Response

Status: 200 OK

[
  {
    "visitor_key": "E4E7613B5C24CB0F1F7C0A1E4E874635E752263E",
    "created_at": "2012-12-12T01:51:36Z",
    "last_active_at": "2012-12-12T03:15:56Z",
    "last_event_key": "1355282055737f0.4801975437439978",
    "load_count": 3,
    "play_count": 2,
    "identifying_event_key": 1390862572596e0.8447021404281259,
    "visitor_identity": {
      "name": "Jim",
      "email": "jim@example.com",
      "org": {
        "name": "Jeff's Lemonade",
        "title": "Expert lemon squeezer"
      }
    },
    "user_agent_details":  {
      "browser": "Chrome",
      "browser_version": "45",
      "platform": "mac",
      "mobile": false
    }
  },
  {
    "visitor_key": "9DC9D7F525236E25E27E9743C0524DB0F02C703D",
    "created_at": "2011-12-15T22:20:08Z",
    "last_active_at": "2012-12-12T03:13:52Z",
    "last_event_key": "1355282030102f0.8788125906139612",
    "load_count": 17,
    "play_count": 9,
    "identifying_event_key": null,
    "visitor_identity": {
      "name": null,
      "email": null,
      "org": {
        "name": null,
        "title": null
      }
    },
    "user_agent_details":  {
      "browser": "Chrome",
      "browser_version": "45",
      "platform": "mac",
      "mobile": false
    }
  }
]

Visitors: Show

This method allows you to retrieve the information for a single visitor.

The Request

GET https://api.wistia.com/v1/stats/visitors/[visitor-key].json

Parameters

This method does not take any parameters besides the visitor-key that is already specified in the URL.

The Response

The response will be a single object representing the visitor's information. It contains the following fields:

FieldDescription
visitor_keyThis is a unique identifier for the visitor.
created_atWhen the visitor was created - i.e. when they first loaded a video in the account.
last_active_atThe last time the visitor played a video.
last_event_keyThe event key that can be used to retrieve the information about what happened when they last played a video.
load_countThe total number of videos that have been loaded (but not necessarily viewed) by this visitor.
play_countThe total number of videos that have been viewed by this visitor.
visitor_identityAn object with 3 fields (name, email, and org) that represents the available identity info for this visitor.
user_agent_detailsAn object with 4 fields: browser (e.g. 'Chrome'), browser_version (e.g. '46'), platform (e.g. 'mac'), and mobile (boolean value stating whether the visitor was on their mobile phone.)

Example JSON Response

Status: 200 OK

{
  "visitor_key": "E4E7613B5C24CB0F1F7C0A1E4E874635E752263E",
  "created_at": "2012-12-12T01:51:36Z",
  "last_active_at": "2012-12-12T03:15:56Z",
  "last_event_key": "1355282055737f0.4801975437439978",
  "load_count": 3,
  "play_count": 2,
  "visitor_identity": {
    "name": "Jim",
    "email": "jim@example.com",
    "org": {
      "name": "Jim's Lemonade",
      "title": "Expert lemon squeezer"
    }
  },
  "user_agent_details":  {
    "browser": "Chrome",
    "browser_version": "45",
    "platform": "mac",
    "mobile": false
  }
}

Events

Events: List

This method allows you to retrieve a list of events (viewing sessions) from your account.

The Request

GET https://api.wistia.com/v1/stats/events.json

Parameters

ParameterDescription
media_idAn optional parameter specifying the video for which you would like to retrieve events.
visitor_keyAn optional parameter specifying the visitor for which you would like to retrieve events.
per_pageThe maximum number of events to retrieve. This number is capped at 100. If you need to get more than 100 events, please issue multiple requests.
pageThe page of events to get data from, based on the per_page parameter.
start_dateAn optional parameter indicating that events should only be returned after the given date. Takes the format '2012-11-25'.
end_dateAn optional parameter indicating that events should only be returned before the given date. Takes the format '2012-11-25'.

The Response

The response will be an array of objects. Each one represents a single viewing session (event) and has the following fields:

FieldDescription
received_atThe date and time that the event happened.
event_keyThe ID for that event.
visitor_keyThe id of the visitor, which can be used to retrieve further information about them.
embed_urlThe URL of the page where the video was viewed.
percent_viewedThe decimal number denoting how much of the video was watched during this session (0 to 1).
ipThe viewer's IP address.
orgThe organization that the IP address belongs to.
countryThe viewer's country, based on IP.
regionThe viewer's region, based on IP.
cityThe viewer's city, based on IP.
latThe latitude of the viewer's IP.
lonThe longitude of the viewer's IP.
emailThe viewer's email address, if available.
media_idAn identifier indicating which video was watched.
media_urlThe video's URL in the Wistia account.
media_nameThe name of the video.
iframe_heatmap_urlThe URL of an HTML page that will render the heatmap for this event.

Example JSON Response

Status: 200 OK

[
  {
    "received_at": "2014-01-27T22:42:53Z",
    "event_key": "1390862572596e0.8447021404281259",
    "ip": "64.95.172.26",
    "country": "US",
    "region": "WA",
    "city": "Seattle",
    "lat": 47.6103,
    "lon": -122.334,
    "org": "Onvia.com",
    "email": null,
    "percent_viewed": 0.22457664233576624,
    "embed_url": "http://wistia.github.io/demobin/post-roll-video-play/",
    "conversion_type": "",
    "conversion_data": {
      "email": "test@wistia.com",
      "first_name" : "Jeff",
      "last_name"  : "Vincent"
    },
    "iframe_heatmap_url": "https://api.wistia.com/v1/stats/events/1390862572596e0.8447021404281259/iframe.html?public_token=xxxxxx",
    "visitor_key": "B6D1F47963577AF26697138FAB75BD1B7086697B",
    "media_id": "993554ba94",
    "media_name": "How They Work - Help Scout",
    "media_url": "https://jeff.wistia.com/medias/993554ba94",
    "thumbnail": {
      "url": "http://embed.wistia.com/deliveries/48fbdd30054000aa548938ef436dfb1a190d34c5.bin",
      "width": 640,
      "height": 360,
      "fileSize": 32720,
      "contentType": "image/jpeg",
      "type": "StillImageFile"
    }
  },
  {
    "received_at": "2014-01-27T20:54:31Z",
    "event_key": "1390856239396e0.3702384910728902",
    "ip": "186.137.141.112",
    "country": "AR",
    "region": "07",
    "city": "Buenos Aires",
    "lat": -34.5875,
    "lon": -58.6725,
    "org": "CABLEVISION S.A.",
    "email": null,
    "percent_viewed": 0.04356993736951984,
    "embed_url": "http://wistia.github.io/demobin/multiple-plays-at-once/",
    "conversion_type": "",
    "conversion_data": {
      "email": "test@wistia.com",
      "first_name" : "Jeff",
      "last_name"  : "Vincent"
    },
    "iframe_heatmap_url": "https://api.wistia.com/v1/stats/events/1390856239396e0.3702384910728902/iframe.html?public_token=xxxxxx",
    "visitor_key": "7C1125427A252C6DE06FDC2B007712911DAF17B7",
    "media_id": "r2wybv7xr0",
    "media_name": "2012 Recap",
    "media_url": "https://jeff.wistia.com/medias/r2wybv7xr0",
    "thumbnail": {
      "url": "http://embed.wistia.com/deliveries/34d01c07ff2da906b092c8ba1c75b0c345006340.bin",
      "width": 1280,
      "height": 720,
      "fileSize": 191752,
      "contentType": "image/jpeg",
      "type": "StillImageFile"
    }
  }
]

Events: Show

This method gives you the information about a single event from your account.

The Request

GET https://api.wistia.com/v1/stats/events/[event-key].json

Parameters

This method does not take any parameters other than the event key already specified in the URL.

The Response

The response will be a single object representing the information about the event. The format and fields of this object will be the same as can be found in the Events: List method.

Example JSON Response

Status: 200 OK

{
  "received_at": "2014-01-27T22:42:53Z",
  "event_key": "1390862572596e0.8447021404281259",
  "ip": "64.95.172.26",
  "country": "US",
  "region": "WA",
  "city": "Seattle",
  "lat": 47.6103,
  "lon": -122.334,
  "org": "Onvia.com",
  "email": null,
  "percent_viewed": 0.22457664233576624,
  "embed_url": "http://wistia.github.io/demobin/post-roll-video-play/",
  "conversion_type": "",
  "conversion_data": {
      "email": "test@wistia.com",
      "first_name" : "Jeff",
      "last_name"  : "Vincent"
    },
  "iframe_heatmap_url": "https://api.wistia.com/v1/stats/events/1390862572596e0.8447021404281259/iframe.html?public_token=xxxxxxx",
  "visitor_key": "B6D1F47963577AF26697138FAB75BD1B7086697B",
  "media_id": "993554ba94",
  "media_name": "How They Work - Help Scout",
  "media_url": "https://jeff.wistia.com/medias/993554ba94",
  "thumbnail": {
    "url": "http://embed.wistia.com/deliveries/48fbdd30054000aa548938ef436dfb1a190d34c5.bin",
    "width": 640,
    "height": 360,
    "fileSize": 32720,
    "contentType": "image/jpeg",
    "type": "StillImageFile"
  }
}

Events: Heatmap

You can get the heatmap for any event by constructing the following URL:

GET https://api.wistia.com/v1/stats/events/[event-key]/iframe.html?public_token=[public_token]

Replace the <event-key> token with the event_key that indicates which heatmap you would like to see. You can get the <event-key> value from other parts of this API or from the Wistia player itself.

Make sure you also provide your account's <public_token> as a parameter. You can find your <public_token> by clicking on API in your Account Settings.

This URL is meant to be used as the target of an iframe which can then be used to render the heatmap within your own pages.

Here is an example heatmap embedded right into this page:

Here is the code that we used to embed the heatmap:

<iframe src="https://api.wistia.com/v1/stats/events/1355283144880f0.12204939918592572/iframe.html?public_token=p5j1mnpakv" height="70" width="100%" style="border: solid 2px black;"></iframe>