SproutVideo API Documentation

Getting Started

The SproutVideo API allows you to interact with your SproutVideo account with a RESTful API. With it, you can upload, list, modify, and delete videos, create, modify and delete tags, and create, modify, and delete playlists.

Schema

All access is over HTTPS and accessed from the api.sproutvideo.com domain. All data is sent and received as JSON.

Blank fields are included as null instead of being omitted.

All timestamps and datetime fields should be in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Authentication

Authentication is achieved by setting the SproutVideo-Api-Key header to your api key in each request.

You can find your api key by logging in to your account and clicking on the "Account" link in the upper right.

Pagination

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the ?page parameter. You can also set a custom page size up to 100 with the ?per_page parameter.

The pagination info is included in the JSON response

{
  "total": 35,
  "next_page": "https://api.sproutvideo.com/v1/videos?page=3&per_page=25",
  "previous_page": "https://api.sproutvideo.com/v1/videos?page=1&per_page=25",
  ...
}

Pagination Response

Name Descrition
total The total number of items in the collection
next_page The URI of the next page of items in the collection if there are more pages
previous_page The URI for the previous page of items in the collection if there are previous pages

PUT and DELETE

Some HTTP clients are limited to sending GET and POST requests (e.g. HTML forms have this limitation). You will notice, however, that many of the API calls only respond to PUT or DELETE requests. In order to trigger these calls from a client that does not support PUT or DELETE, use a POST request and add a parameter named "_method" (no quotes) with a value of either "put" or "delete" (again, no quotes).

Rate Limit

The API has a rate limit at 100 requests per minute. If there are more than 100 requests in a minute for a particular account, the service will respond with HTTP error 503.

Videos

Note: Embed codes will not be usable until the video state is deployed

Video Privacy

Videos on SproutVideo can have one of several differenct privacy settings:
Privacy Level Name Description
0 Private This video can only be viewed on SproutVideo.com by the owner of the video. It, however, can still be embedded anywhere.
1 Password Protected his video requires a password to be viewed. It, however, can still be embedded anywhere. If prefers_embed_password is set to true the embedded video will ask for the password before it can be viewed.
2 Public Anyone can view this video and it can be embedded anywhere.
3 Login protected A login with a valid access grant to this video is required in order to view the video. Embedded videos will require the viewer to log in before being able to watch the video.

Video States

Videos on SproutVideo can be in one of several different states:
State Description
Inspecting The video and it's metadata are being inspected to prepare the video for processing.
Processing The video is being processed and converted into several different formats for optmial playback on the web and mobile devices. You can check on the progress of this step by looking at the progress field for a video.
Deployed The video is finished processing and has been deployed to our CDN. This video can now be watched.
Failed The video failed to process correctly. Please contact support if you run into this issue and are unable to resolve it.

List your videos

URL Method
https://api.sproutvideo.com/v1/videos GET

Inputs

Name Required? Type Description
order_by Optional String Order the results by one of the following: created_at, updated_at, duration, title. Example: https://api.sproutvideo.com/v1/videos?order_by=updated_at
order_dir Optional String The direction in which the results should be sorted. Use asc to sort in ascending order and desc to sort in descending order. Example: https://api.sproutvideo.com/v1/videos?order_by=duration&order_dir=desc
tag_id Optional String Retrieve only the videos tagged with this tag id. Example: https://api.sproutvideo.com/v1/videos?tag_id=a323d32
tag_name Optional String Retrieve only the videos tagged with this tag name. Example: https://api.sproutvideo.com/v1/videos?tag_name=funny+cat+videos
privacy Optional Integer Only display results with the specified privacy. Use the privacy values in the table above. Example: https://api.sproutvideo.com/v1/videos?privacy=2
state Optional String Only display results in the specified state. Use the state values in the table above. Example: https://api.sproutvideo.com/v1/videos?state=processing

Response

Name Type Description
total Integer The total number of videos in the account
next_page String The URL of the next page of the collection (if there are more pages)
previous_page String The URL of the previous page of the collection (if there are previous pages)
videos Array An array containing video objects. See the response of getting a single video for the items in a video.

Example

{
  "next_page": "http://api.sproutvideo.com/v1/videos?page=2&per_page=25",
  "total": 41,
  "videos": [
    {
      "created_at": "2010-08-26T21:35:41-04:00",
      "updated_at": "2012-12-20T00:07:54-05:00",
      "height": 540,
      "width": 960,
      "description": "An example movie",
      "id": "a098d2bbd33e1c328",
      "sd_video_file_size": 8085470,
      "plays": 348,
      "title": "example.mov",
      "source_video_file_size": 0,
      "hd_video_file_size": 15707800,
      "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='http://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d?type=sd' width='630' height='354' frameborder='0'></iframe>",
      "state": "deployed",
      "security_token": "7ca00d6d622a8e8d",
      "progress": 100,
      "tags": [
        "4a32d29b4c4"
      ],
      "embedded_url": null,
      "duration": 73,
      "password": null,
      "privacy": 0,
      "requires_signed_embeds": false,
      "selected_poster_frame_number": 0,
      "assets": {
        "videos": {
          "hd_video_url": "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/videos/hd/d2746e08d99b1da272bc4f553d.mp4",
          "sd_video_url": "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/videos/iphone/d2746e08d99b1da272bc4f553d.mp4",
          "source_video_url": null
        },
        "thumbnails": [
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0000.jpg",
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0001.jpg",
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0002.jpg",
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0003.jpg",
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0004.jpg",
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0005.jpg"
        ],
        "poster_frames": [
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0000.jpg",
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0001.jpg",
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0002.jpg",
          "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0003.jpg"
        ]
      }
    },
    ...
  }

Get a single video

URL Method
https://api.sproutvideo.com/v1/videos/:id GET

Response

Name Type Description
id String The id of this video
width Integer The width of the uploaded video
height Integer The height of the uploaded video
embed_code String The embed code for this video
source_video_file_size Integer The file size of the file uploaded to SproutVideo in bytes
sd_video_file_size Integer the file size of the SD version of the video in byte, if it exists
hd_video_file_size Integer the file size of the HD version of the video in bytes, if it exists
security_token String The security token for this video
title String The title of the video
description String The description for this video
duration Integer The duration of the video in seconds
privacy String The privacy setting for the video.
password String The password for this video if it is set
state String The current state of the video.
tags Array An array of tag ids with which this video is tagged
created_at String The date at which the video was uploaded
updated_at String The date when the last edit to this video occured
plays Integer The number of times this video has been played
progress Integer The current progress of the video in the encoding process
requires_signed_embeds Boolean Indicates if signed embed codes are required for this video
selected_poster_frame_number Integer The currently selected poster frame number.
embedded_url String The URL where the video is embedded. This is used for Video Sitemaps.
assets Array An array containing all of the assets associated with the video
Name Type Description
thumbnails Array An array of URLs for the thumbnails for this video
poster_frames Array An array of URLS for the poster frame for this video
videos Object An object containing the video assets:
Name Type Description
sd_video_url String The url for the SD version of this video if it exists
hd_video_url String The url for the HD version of this video if it exists
source_video_url String the url for the originally uploaded version of this video if it exists

Example

{
  "created_at": "2010-08-26T21:35:41-04:00",
  "updated_at": "2012-12-20T00:07:54-05:00",
  "height": 540,
  "width": 960,
  "description": "An example movie",
  "id": "a098d2bbd33e1c328",
  "sd_video_file_size": 8085470,
  "plays": 348,
  "title": "example.mov",
  "source_video_file_size": 0,
  "hd_video_file_size": 15707800,
  "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='http://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d?type=sd' width='630' height='354' frameborder='0'></iframe>",
  "state": "deployed",
  "security_token": "7ca00d6d622a8e8d",
  "progress": 100,
  "tags": [
    "4a32d29b4c4"
  ],
  "embedded_url": null,
  "duration": 73,
  "password": null,
  "privacy": 0,
  "requires_signed_embeds": false,
  "selected_poster_frame_number": 0,
  "assets": {
    "videos": {
      "hd_video_url": "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/videos/hd/d2746e08d99b1da272bc4f553d.mp4",
      "sd_video_url": "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/videos/iphone/d2746e08d99b1da272bc4f553d.mp4",
      "source_video_url": null
    },
    "thumbnails": [
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0000.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0001.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0002.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0003.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0004.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0005.jpg"
    ],
    "poster_frames": [
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0000.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0001.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0002.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0003.jpg"
    ]
  }
}

Upload a new video

URL Method
https://api.sproutvideo.com/v1/videos POST
Note: While all other API methods, except for when uploading a poster frame, accept a JSON body as their input, this method only accepts input as multipart/form-data.
If you attempt to upload a video with a file extension we do not currently support, you will receive a response code of 415 - Unsupported Media Type. The upload will not be processed and the response body will contain a list of the currently supported file extensions.
If your plan has storage limits and the file you attempt to upload would put you over your limit, you will receive a response code of 413 - Request Entity Too Large and the upload will not be processed.

Inputs

Name Required? Type Description
source_video Required Video File The actual contents of the video to be uploaded
title Optional String The title of the video (Defaults to the file name of the uploaded video)
description Optional String An optional description for the video
privacy Optional Integer The privacy setting for the video (Defaults to the default value for the account)
password Optional String The password for the video if the video's privacy setting is set to 1
prefers_embed_password Optional Boolean If the privacy value is set to 1 and there is a password set for the video, setting prefers_embed_password to true will require a viewer to enter the password before being able to watch the video. Setting prefers_embed_password to false will make the video not require a password before being able to view the video.
tags Optional Array of Strings Tags to associate with the video. Pass one or more tags ids to add the set of tags to the video. Example: ["4a32d29b4c4", "82dbbde97a"]
tag_names Optional Array of Strings Tags to associate with the video. Pass on or more tag names to add the set of tags to the video. This allows you to create new tags on the fly without having to create them first in another API call. Example: ["Tag One", "Tag Two"]
notification_url Optional String After the video is done processing, we will attempt an HTTP POST with the JSON metadata about the video to the URL specified in this field. The body of the post is the same as the response for getting a single video
requires_signed_embeds Optional Boolean Indicates if signed embed codes are required for this video
embedded_url Optional String The URL where the video is embedded. This is used for Video Sitemaps.
token Optional String The token generated by an upload token request. This allows you to upload videos directly through a browser without having to proxy the upload through a server.

Response

The response for this call is the same as the response for getting a single video

Example

{
  "created_at": "2012-12-20T00:07:54-05:00",
  "updated_at": "2012-12-20T00:07:54-05:00",
  "height": null,
  "width": null,
  "description": "An new video",
  "id": "a098d2bbd33e1c328",
  "sd_video_file_size": 0,
  "plays": 0,
  "title": "new upload.mov",
  "source_video_file_size": 0,
  "hd_video_file_size": 0,
  "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='http://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d?type=sd' width='630' height='354' frameborder='0'></iframe>",
  "state": "inspecting",
  "security_token": "7ca00d6d622a8e8d",
  "progress": 0,
  "tags": [],
  "embedded_url": null,
  "duration": null,
  "password": null,
  "privacy": 2,
  "requires_signed_embeds": false,
  "selected_poster_frame_number": 0,
  "assets": {
    "videos": {
      "hd_video_url": null,
      "sd_video_url": null,
      "source_video_url": null
    },
    "thumbnails": [],
    "poster_frames": []
  }
}

Token-Based Uploads

It is possible to upload videos directly from a browser without having to proxy the upload through a server by using a one-time use upload token. This allows you to perform uploads from the browser without exposing your API key. Upload tokens can only be used once so you need to generate a new one each time you intend to upload a video. Once you have generated a token, you can upload a video through the browser using all of the same inputs as a regular video upload. We support both uploads from a simple form and though AJAX. For regular form uploads, specify a return_url. This is where the browser will be redirected after the upload is complete. If the upload is successful, we'll append query parameters that specify both that the upload was successful and the video id of the newly uploaded video, like this ?successful=true&video_id=abcd1234. If the upload fails, we will append query parameters that specify both that the upload failed and a human readable error message, like this ?successful=false&error_message=Invalid%20Upload%20Token. AJAX uploads will return the normal output from the regular upload API method.

URL Method
https://api.sproutvideo.com/v1/upload_tokens POST

Inputs

Name Requrired? Type Description
return_url Optional String The url to which you'd like the browser to be redirected after the upload has completed. If you're uploading using AJAX, don't include this field.
seconds_valid Optional Integer Default: 10800 (3 hours). The number of seconds the upload token will remain valid. Make sure to appropriate enough time for the whole upload to complete.

Example

Request Body
{
  "return_url": "http://example.com",
  "seconds_valid": 3600
}

This will create an upload token that is valid for one hour and redirects back to http://example.com after the upload has completed.

Response Body
{
  "token": "41d92bec0ab07a1fc3a0c3ddaa748743"
  "return_url": "http://example.com",
  "seconds_valid": 3600,
  "expires_at": "2014-07-07T23:08:37+00:00"
}

Use the token string when performing an upload from the browser.

Edit a video

URL Method
https://api.sproutvideo.com/v1/videos/:id PUT

Inputs

Name Required? Type Description
title Optional String The title of the video (Defaults to the file name of the uploaded video)
description Optional String An optional description for the video
privacy Optional Integer The privacy setting for the video (Defaults to the default value for the account)
posterframe_number Optional Integer Which of the four generated poster frames to use for the video
password Optional String The password for the video if the video's privacy setting is set to 1
prefers_embed_password Optional Boolean If the privacy value is set to 1 and there is a password set for the video, setting prefers_embed_password to true will require a viewer to enter the password before being able to watch the video. Setting prefers_embed_password to false will make the video not require a password before being able to view the video.
tags Optional Array of Strings Tags to associate with the video. Pass one or more tag ids to replace the set of tags on this video. Send an empty array [ ] to clear all tags from the video.
requires_signed_embeds Optional Boolean Indicates if signed embed codes are required for this video
embedded_url Optional String The URL where the video is embedded. This is used for Video Sitemaps.

Response

The response for this call is the same as the response for getting a single video

Example

Request Body
{
  "title":"An amazing video",
  "description": "This really is an amazing video!",
  "privacy": 1,
  "password": "video password",
  "prefers_embed_password": true,
  "tags": ["82dbbde97a"]
}
Response Body
{
  "created_at": "2010-08-26T21:35:41-04:00",
  "updated_at": "2012-12-20T00:07:54-05:00",
  "height": 540,
  "width": 960,
  "description": "This really is an amazing video!",
  "id": "a098d2bbd33e1c328",
  "sd_video_file_size": 8085470,
  "plays": 348,
  "title": "An amazing video",
  "source_video_file_size": 0,
  "hd_video_file_size": 15707800,
  "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='http://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d?type=sd' width='630' height='354' frameborder='0'></iframe>",
  "state": "deployed",
  "security_token": "7ca00d6d622a8e8d",
  "progress": 100,
  "tags": [
    "82dbbde97a"
  ],
  "embedded_url": null,
  "duration": 73,
  "password": "video password",
  "privacy": 1,
  "requires_signed_embeds": false,
  "selected_poster_frame_number": 0,
  "assets": {
    "videos": {
      "hd_video_url": "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/videos/hd/d2746e08d99b1da272bc4f553d.mp4",
      "sd_video_url": "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/videos/iphone/d2746e08d99b1da272bc4f553d.mp4",
      "source_video_url": null
    },
    "thumbnails": [
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0000.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0001.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0002.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0003.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0004.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0005.jpg"
    ],
    "poster_frames": [
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0000.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0001.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0002.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0003.jpg"
    ]
  }
}

Upload a poster frame

URL Method
https://api.sproutvideo.com/v1//videos/:id PUT
You can upload a new, custom, poster frame using this API method. The newly uploaded poster frame will automatically overwrite any other uploaded poster frames and be automatically selected as the poster frame for your video.
Note: Like the upload video API method, this method only accepts input as multipart/form-data not not JSON.
If you attempt to upload a poster frame with a file extension we do not currently support, you will receive a response code of 415 - Unsupported Media Type. The upload will not be processed and the response body will contain a list of the currently supported file extensions. We currently only support jpeg files.
Poster frames must be under 500 kilobytes. You will receive a response code of 413 - Request Entity Too Large if the file you upload is larger than 500 kilobytes.

Inputs

Name Required? Type Description
custom_poster_frame Required Jpeg image The actual contents of the poster frame to be uploaded. (Must be under 500 kilobytes)

Response

{
  "created_at": "2010-08-26T21:35:41-04:00",
  "updated_at": "2012-12-20T00:07:54-05:00",
  "height": 540,
  "width": 960,
  "description": "This really is an amazing video!",
  "id": "a098d2bbd33e1c328",
  "sd_video_file_size": 8085470,
  "plays": 348,
  "title": "An amazing video",
  "source_video_file_size": 0,
  "hd_video_file_size": 15707800,
  "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='http://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d?type=sd' width='630' height='354' frameborder='0'></iframe>",
  "state": "deployed",
  "security_token": "7ca00d6d622a8e8d",
  "progress": 100,
  "tags": [
    "82dbbde97a"
  ],
  "embedded_url": null,
  "duration": 73,
  "password": "video password",
  "privacy": 1,
  "requires_signed_embeds": false,
  "selected_poster_frame_number": 1389903763,
  "assets": {
    "videos": {
      "hd_video_url": "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/videos/hd/d2746e08d99b1da272bc4f553d.mp4",
      "sd_video_url": "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/videos/iphone/d2746e08d99b1da272bc4f553d.mp4",
      "source_video_url": null
    },
    "thumbnails": [
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0000.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0001.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0002.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0003.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0004.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/thumbnails/d2746e08d99b1da272bc4f553d/frame_0005.jpg"
    ],
    "poster_frames": [
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0000.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0001.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0002.jpg",
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_0003.jpg"
      "http://cdn.sproutvideo.com/3d5944db5f967420e4ab256c39b5/posterframes/d2746e08d99b1da272bc4f553d/frame_1389903763.jpg"
    ]
  }
}

Delete a video

URL Method
https://api.sproutvideo.com/v1/videos/:id DELETE

Response

The response for this call is the same as the response for getting a single video. The data for the deleted video will be returned.

Tags

List your tags

URL Method
https://api.sproutvideo.com/v1/tags GET

Inputs

Name Required? Type Description
order_by Optional String Order the results by one of the following: created_at, updated_at, name. Example: https://api.sproutvideo.com/v1/tags?order_by=updated_at
order_dir Optional String The direction in which the results should be sorted. Use asc to sort in ascending order and desc to sort in descending order. Example: https://api.sproutvideo.com/v1/tags?order_by=updated_at&order_dir=desc

Response

Name Type Description
total Integer The total number of tags in the account
next_page String The URL of the next page of the collection (if there are more pages)
previous_page String The URL of the previous page of the collection (if there are previous pages)
tags Array An array containing tag objects. See the response of getting a single tag for the items in a tag.

Example

{
  "total": 12,
  "next_page": "https://api.sproutvideo.com/v1/tags?page=2&per_page=25",
  "tags": [
    {
      "name": "Demo Videos",
      "created_at": "2010-08-27T01:35:41Z",
      "videos": ["06ac1ec1615b2d898e"],
      "updated_at": "2011-05-07T21:55:35Z",
      "id": "82dbbde97a"
    },
    ...
  ]
}

Get a single tag

URL Method
https://api.sproutvideo.com/v1/tags/:id GET

Response

Name Type Description
id String The id of the tag
name String The name of the tag
videos Array An array of video ids of videos tagged with this tag
created_at String The date on which this tag was created
updated_at String The date on which this tag was last updated

Example

{
  "name": "Demo Videos",
  "created_at": "2010-08-27T01:35:41Z",
  "videos": ["06ac1ec1615b2d898e"],
  "updated_at": "2011-05-07T21:55:35Z",
  "id": "82dbbde97a"
}

Create a new tag

URL Method
https://api.sproutvideo.com/v1/tags POST

Inputs

Name Required? Type Description
name Required String The name of the tag

Response

The response for this call is the same as the response for getting a single tag.

Example

Request
{
  "name": "New Tag"
}
Response
{
  "name": "New Tag",
  "created_at": "2012-08-27T01:35:41Z",
  "updated_at": "2012-08-27T01:35:41Z",
  "videos": [],
  "id": "82dbbde97a"
}

Edit a tag

URL Method
https://api.sproutvideo.com/v1/tags/:id PUT

Inputs

Name Required? Type Description
name Optional String The name of the tag

Response

The response for this call is the same as the response for getting a single tag.

Example

Request
{
  "name": "Updated Tag Name"
}
Response
{
  "name": "Updated Tag Name",
  "created_at": "2012-08-27T01:35:41Z",
  "updated_at": "2012-10-27T01:35:41Z",
  "videos": ["06ac1ec1615b2d898e"],
  "id": "82dbbde97a"
}

Delete a tag

URL Method
https://api.sproutvideo.com/v1/tags/:id DELETE

Response

The response for this call is the same as the response for getting a single tag. The data for the deleted tag will be returned.

Playlists

List your playlists

URL Method
https://api.sproutvideo.com/v1/playlists GET

Inputs

Name Required? Type Description
order_by Optional String Order the results by one of the following: created_at, updated_at, duration, title. Example: https://api.sproutvideo.com/v1/playlists?order_by=updated_at
order_dir Optional String The direction in which the results should be sorted. Use asc to sort in ascending order and desc to sort in descending order. Example: https://api.sproutvideo.com/v1/playlists?order_by=updated_at&order_dir=desc
privacy Optional Integer Only display results with the specified privacy. Use the privacy values in the table above. Example: https://api.sproutvideo.com/v1/playlists?privacy=2

Response

Name Type Description
total Integer The total number of playlists in the account
next_page String The URL of the next page of the collection (if there are more pages)
previous_page String The URL of the previous page of the collection (if there are previous pages)
playlists Array An array containing playlists objects. See the response of getting a single playlist for the items in a playlist.

Example

{
  "total": 2,
  "playlists": [
    {
      "created_at": "2011-08-25T18:09:46Z",
      "updated_at": "2012-02-03T19:02:28Z",
      "privacy": 2,
      "password": "",
      "title": "Movie Trailers",
      "security_token": "9c4afc572c2af416",
      "videos": [
        "8b19c6e1560e8da1c2",
        "21a0c9b6ec18ed6815",
        "a02e18cdeb566c1198",
        "081c261c1d5b6e9ae8",
        "a15ee061d288c9c16b",
        "5ce81a011d6b9286ce"
      ],
      "id": "e210c6ad6b1ec88591",
      "embed_code": "<iframe class='sproutvideo-playlist' type='text/html' src='http://videos.sproutvideo.com/playlist/e210c6ad6b1ec88591/9c4afc572c2af416' width='918' height='360' frameborder='0'></iframe>;"
    },
    ...
  ]
}

Get a single playlist

URL Method
https://api.sproutvideo.com/v1/playlists/:id GET

Response

Name Type Description
id String The id of the playlist
security_token String The security token for the playlist
privacy Integer The privacy level for this playlist
password String The password for this playlist if it is password protected
title String The title of the playlist
videos Array An array of video ids of videos in this playlist
embed_code String The embed code for this playlist
created_at String The date on which this playlist was created
updated_at String The date on which this playlist was last edited

Example

{
  "created_at": "2011-08-25T18:09:46Z",
  "updated_at": "2012-02-03T19:02:28Z",
  "privacy": 2,
  "password": "",
  "title": "Movie Trailers",
  "security_token": "9c4afc572c2af416",
  "videos": [
    "8b19c6e1560e8da1c2",
    "21a0c9b6ec18ed6815",
    "a02e18cdeb566c1198",
    "081c261c1d5b6e9ae8",
    "a15ee061d288c9c16b",
    "5ce81a011d6b9286ce"
  ],
  "id": "e210c6ad6b1ec88591",
  "embed_code": "<iframe class='sproutvideo-playlist' type='text/html' src='http://videos.sproutvideo.com/playlist/e210c6ad6b1ec88591/9c4afc572c2af416' width='918' height='360' frameborder='0'></iframe>"
}

Create a new playlist

URL Method
https://api.sproutvideo.com/v1/playlists POST

Inputs

Name Required? Type Description
title Required String The title of the playlist
privacy Optional Integer The privacy level for this playlist. Playlists currently only support privacy levels 0, 1, and 2. Login protected playlists are not supported at this itime. The default privacy level for playlists is 0
password Optional String The password to be used for this playlist if the privacy level is set to 1
videos Optional Array of Strings The videos for this playlist. Pass one or more videos ids to add the set of videos in this playlist. The order of the video ids in the array is the order the videos will appear in the playlist

Response

The response for this call is the same as the response for getting a single playlist.

Example

Request
{
  "title": "New Playlist",
  "videos": [
    "21a0c9b6ec18ed6815",
    "8b19c6e1560e8da1c2",
    "5ce81a011d6b9286ce"
    "081c261c1d5b6e9ae8"
  ]
}
Response
{
  "created_at": "2012-02-03T19:02:28Z",
  "updated_at": "2012-02-03T19:02:28Z",
  "privacy": 0,
  "password": "",
  "title": "New Playlist",
  "security_token": "9c4afc572c2af416",
  "videos": [
    "21a0c9b6ec18ed6815",
    "8b19c6e1560e8da1c2",
    "5ce81a011d6b9286ce"
    "081c261c1d5b6e9ae8"
  ],
  "id": "e210c6ad6b1ec88591",
  "embed_code": "<iframe class='sproutvideo-playlist' type='text/html' src='http://videos.sproutvideo.com/playlist/e210c6ad6b1ec88591/9c4afc572c2af416' width='918' height='360' frameborder='0'></iframe>"
}

Edit a Playlist

URL Method
https://api.sproutvideo.com/v1/playlists/:id PUT

Inputs

Name Required? Type Description
title Optional String The title of the playlist
privacy Optional Integer The privacy level for this playlist. Playlists currently only support privacy levels 0, 1, and 2. Login protected playlists are not supported at this itime. The default privacy level for playlists is 0
password Optional String The password to be used for this playlist if the privacy level is set to 1
videos Optional Array of Strings The videos for this playlist. Make sure to include all videos you wish to be in the playlist in this array. Any videos that were previously in the playlist, but are not in this array, will be removed from the playlist. The order of the video ids in the array is the order the videos will appear in the playlist. Send an empty array([ ]) to clear all videos from the playlist.

Response

The response for this call is the same as the response for getting a single playlist.

Example

Request
{
  "title": "Awesome Movie Trailers",
  "privacy": 2,
  "videos": [
    "5ce81a011d6b9286ce",
    "8b19c6e1560e8da1c2",
    "21a0c9b6ec18ed6815",
    "081c261c1d5b6e9ae8"
  ]
}
Response
{
  "created_at": "2011-08-25T18:09:46Z",
  "updated_at": "2012-02-03T19:02:28Z",
  "privacy": 2,
  "password": "",
  "title": "Awesome Movie Trailers",
  "security_token": "9c4afc572c2af416",
  "videos": [
    "5ce81a011d6b9286ce",
    "8b19c6e1560e8da1c2",
    "21a0c9b6ec18ed6815",
    "081c261c1d5b6e9ae8"
  ],
  "id": "e210c6ad6b1ec88591",
  "embed_code": "<iframe class='sproutvideo-playlist' type='text/html' src='http://videos.sproutvideo.com/playlist/e210c6ad6b1ec88591/9c4afc572c2af416' width='918' height='360' frameborder='0'></iframe>"
}

Delete a playlist

URL Method
https://api.sproutvideo.com/v1/playlists/:id DELETE

Response

The response for this call is the same as the response for getting a single playlist. The data for the deleted playlist will be returned.

Logins

A login is a username and password combination that allows you to grant users access to specific videos. They do not allow others to log in to your account.

List your logins

URL Method
https://api.sproutvideo.com/v1/logins GET

Inputs

Name Required? Type Description
order_by Optional String Order the results by one of the following: created_at, updated_at, email. Example: https://api.sproutvideo.com/v1/logins?order_by=updated_at
order_dir Optional String The direction in which the results should be sorted. Use asc to sort in ascending order and desc to sort in descending order. Example: https://api.sproutvideo.com/v1/logins?order_by=updated_at&order_dir=desc
email Optional String Search for a specific login by email address. Example: https://api.sproutvideo.com/v1/logins?email=test%40example.com

Response

Name Type Description
total Integer The total number of logins in the account
next_page String The URL of the next page of the collection (if there are more pages)
previous_page String The URL of the previous page of the collection (if there are previous pages)
logins Array An array containing logins objects. See the response of getting a single login for the items in a login.

Example

{
  "total": 12,
  "next_page": "https://api.sproutvideo.com/v1/logins?page=2&per_page=25",
  "logins": [
    {
      "email": "test@example.com",
      "created_at": "2010-08-27T01:35:41Z",
      "access_grants": ["c25d194a"],
      "updated_at": "2011-05-07T21:55:35Z",
      "id": "06edb9ee"
    },
    ...
  ]
}

Get a single login

URL Method
https://api.sproutvideo.com/v1/logins/:id GET

Response

Name Type Description
id String The id of the login
email String The email address for the login
access_grants Array An array of accesst grant ids of the access grants associated with this login
created_at String The date on which this login was created
updated_at String The date on which this login was last edited

Example

{
  "email": "test@example.com",
  "created_at": "2010-08-27T01:35:41Z",
  "access_grants": ["c25d194a"],
  "updated_at": "2011-05-07T21:55:35Z",
  "id": "06edb9ee"
}

Create a new login

URL Method
https://api.sproutvideo.com/v1/logins POST

Inputs

Name Required? Type Description
email Required String The email address for the login
password Required String The password for this login

Response

The response for this call is the same as the response for getting a single login.

Example

Request
{
  "email": "test@example.com",
  "password": "thisisthepassword"
}
Response
{
  "email": "test@example.com",
  "created_at": "2011-05-07T21:55:35Z",
  "access_grants": [],
  "updated_at": "2011-05-07T21:55:35Z",
  "id": "06edb9ee"
}

Edit a login

URL Method
https://api.sproutvideo.com/v1/logins/:id PUT

Inputs

Name Required? Type Description
password Required String The new password for this login

Response

The response for this call is the same as the response for getting a single login.

Example

Request
{
  "password": "thisisthenewpassword"
}
Response
{
  "email": "test@example.com",
  "created_at": "2010-08-27T01:35:41Z",
  "access_grants": ["c25d194a"],
  "updated_at": "2011-05-07T21:55:35Z",
  "id": "06edb9ee"
}

Delete a login

URL Method
https://api.sproutvideo.com/v1/logins/:id DELETE

Response

The response for this call is the same as the response for getting a single login. The data for the deleted login will be returned.

Access Grants

List your access grants

URL Method
https://api.sproutvideo.com/v1/access_grants GET

Inputs

Name Required? Type Description
order_by Optional String Order the results by one of the following: created_at, updated_at. Example: https://api.sproutvideo.com/v1/access_grants?order_by=updated_at
order_dir Optional String The direction in which the results should be sorted. Use asc to sort in ascending order and desc to sort in descending order. Example: https://api.sproutvideo.com/v1/access_grants?order_by=updated_at&order_dir=desc
video_id Optional String Retrieve access grants for a specific video. Example: https://api.sproutvideo.com/v1/access_grants?video_id=abc123
login_id Optional String Retrieve access grants for a specific login. Example: https://api.sproutvideo.com/v1/access_grants?login_id=abc123

Response

Name Type Description
total Integer The total number of videos in the account
next_page String The URL of the next page of the collection (if there are more pages)
previous_page String The URL of the previous page of the collection (if there are previous pages)
access_grants Array An array containing access grant objects. See the response of getting a single access grant for the items in an access grant.

Example

{
  "total": 12,
  "next_page": "https://api.sproutvideo.com/v1/access_grants?page=2&per_page=25",
  "access_grants": [
    {
      "updated_at": "2012-08-03T18:44:33Z",
      "play_count": 1,
      "allowed_plays": 0,
      "access_starts_at": null,
      "login_id": "1da5",
      "access_ends_at": null,
      "download_permissions": [ ],
      "video_id": "49fc3ee1215b2d89c1",
      "id": "52998a",
      "created_at": "2012-04-28T16:08:32Z"
    },
    ...
  ]
}

Get a single access grant

URL Method
https://api.sproutvideo.com/v1/access_grants/:id GET

Response

Name Type Description
id String The id of the access grant
video_id String The id of the video to which this access grant is granting access
access_starts_at String The date on which access to this video should start
access_ends_at String The date on which access to this video should end
allowed_plays Integer The number of times the viewer may login in to watch the video
play_count Integer The number of times the viewer has played the video
login_id string The id of the login which is being granted access
download_permissions Array An array containing which versions of the video the viewer is allowed to download
created_at String The date on which this access grant was created
updated_at String The date on which this access grant was last edited

Example

{
  "updated_at": "2012-08-03T18:44:33Z",
  "play_count": 1,
  "allowed_plays": 0,
  "access_starts_at": null,
  "login_id": "1da5",
  "access_ends_at": null,
  "download_permissions": [ ],
  "video_id": "49fc3ee1215b2d89c1",
  "id": "52998a",
  "created_at": "2012-04-28T16:08:32Z"
}

Create a new access grant

URL Method
https://api.sproutvideo.com/v1/access_grants POST

Inputs

Name Required? Type Description
login_id Required String The id for the login to which you'd like to grant access
video_id Requried String The id for the video to which you'd like to grant access
allowed_plays Optional Integer The number of times the login may be used to view the video. Passing in 0 means that the login may be used an unlimited number of time. 0 is the default value
access_starts_at Optional String The date on which the login will start to have access to the video. Setting this value to null will mean that the login will have immediate access to the video. null is the default value
access_ends_at Optional String The date at which the login's access to the video will expire. Setting this value to null will mean that the login's access to the video will never expire. null is the default value
download_permissions Optional Array of Strings Which versions of the video the login will be able to download. Currently there are three options original, hd, and sd. The default value is [ ] which means none of the versions are available for download

Response

The response for this call is the same as the response for getting a single access grant

Example

Request
{
  "login_id": "1da5",
  "video_id": "49fc3ee1215b2d89c1",
  "allowed_plays": 5,
  "download_permissions": ["original", "hd"],
  "access_ends_at": "2014-08-03T21:56:03Z"
}
Response
{
  "updated_at": "2012-08-03T18:44:33Z",
  "play_count": 1,
  "allowed_plays": 5,
  "access_starts_at": null,
  "login_id": "1da5",
  "access_ends_at": "2014-08-03T21:56:03Z",
  "download_permissions": ["original", "hd"],
  "video_id": "49fc3ee1215b2d89c1",
  "id": "52998a",
  "created_at": "2012-08-03T18:44:33Z"
}

Edit an access grant

URL Method
https://api.sproutvideo.com/v1/access_grants/:id PUT

Inputs

Name Required? Type Description
allowed_plays Optional Integer The number of times the login may be used to view the video. Passing in 0 means that the login may be used an unlimited number of time. 0 is the default value
access_starts_at Optional String The date on which the login will start to have access to the video. Setting this value to null will mean that the login will have immediate access to the video. null is the default value
access_ends_at Optional String The date at which the login's access to the video will expire. Setting this value to null will mean that the login's access to the video will never expire. null is the default value
download_permissions Optional Array of Strings Which versions of the video the login will be able to download. Currently there are three options original, hd, and sd. The default value is [ ] which means none of the versions are available for download

Response

The response for this call is the same as the response for getting a single access grant

Example

Request
{
  "allowed_plays": 0,
  "download_permissions": ["sd"],
  "access_ends_at": null
}
Response
{
  "updated_at": "2012-08-03T18:44:33Z",
  "play_count": 1,
  "allowed_plays": 0,
  "access_starts_at": null,
  "login_id": "1da5",
  "access_ends_at": null,
  "download_permissions": ["sd"],
  "video_id": "49fc3ee1215b2d89c1",
  "id": "52998a",
  "created_at": "2012-04-28T16:08:32Z"
}

Delete an access grant

URL Method
https://api.sproutvideo.com/v1/access_grants/:id DELETE

Response

The response for this call is the same as the response for getting a single access grant. The data for the deleted access grant will be retuned.

Analytics

Analytics data is only available to account which are on plans that include analytics or engagement data

Play Counts

Overall

URL Method
https://api.sproutvideo.com/v1/stats/counts GET
Response
Name Type Description
play_count Integer The total number of plays across all of your videos
impression_count Integer The total number of times your videos have been displayed on a webpage
unique_play_count Integer The total number of unique individuals who have played your videos
unique_impression_count Integer The total number of unqiue individuals who have seen your video on a webpage
Example
{
  "play_count": 16189,
  "impression_count": 201216,
  "unique_play_count": 8146,
  "unique_impression_count": 65950
}

Overall, By Date

Inputs
Name Required? Type Description
start_date Optional date The beginning of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
start_date Optional date The end of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data
play_count Integer The total number of plays across all of your videos
impression_count Integer The total number of times your videos have been displayed on a webpage
unique_play_count Integer The total number of unique individuals who have played your videos
unique_impression_count Integer The total number of unqiue individuals who have seen your video on a webpage
Example
[
  {
    "date": "2012-12-31",
    "play_count": 21,
    "impression_count": 270,
    "unique_play_count": 16,
    "unique_impression_count": 187
  },
  {
    "date": "2013-01-01",
    "play_count": 42,
    "impression_count": 366,
    "unique_play_count": 34,
    "unique_impression_count": 240
  },
  ...
]

Per Video

URL Method
https://api.sproutvideo.com/v1/stats/counts/:video_id GET
Response
Name Type Description
play_count Integer The total number of plays for this video
impression_count Integer The total number of times this video has been displayed on a webpage
unique_play_count Integer The total number of unique individuals who have played this videos
unique_impression_count Integer The total number of unqiue individuals who have seen this video on a webpage
Example
{
  "play_count": 6485,
  "impression_count": 122169,
  "unique_play_count": 5245,
  "unique_impression_count": 57146
}

Per Video, By Date

Inputs
Name Required? Type Description
start_date Optional date The beginning of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
start_date Optional date The end of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data
play_count Integer The total number of plays for this videos
impression_count Integer The total number of times this video has been displayed on a webpage
unique_play_count Integer The total number of unique individuals who have played this video
unique_impression_count Integer The total number of unqiue individuals who have seen this video on a webpage
Example
[
  {
    "date": "2012-12-31",
    "play_count": 7,
    "impression_count": 201,
    "unique_play_count": 7,
    "unique_impression_count": 157
  },
  {
    "date": "2013-01-01",
    "play_count": 6,
    "impression_count": 204,
    "unique_play_count": 6,
    "unique_impression_count": 150
  },
  ...
]

Domains

URL Method
https://api.sproutvideo.com/v1/stats/domains GET

Overall

Response
Name Type Description
domain String The domain on which the plays occured
play_count Integer The total number of plays that occured on that domain
Example
[
  {
    "play_count": 9743,
    "domain": "example1.com"
  },
  {
    "play_count": 1547,
    "domain": "example2.com"
  },
  ...
]

Overall, By Date

Inputs
Name Required? Type Description
start_date Optional date The beginning of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
start_date Optional date The end of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data
domains Array An array of domains and their play counts for that particular date
Example
[
  {
    "domains": [
      {
        "play_count": 11,
        "domain": "example1.com"
      },
      {
        "play_count": 5,
        "domain": "example2.com"
      }
    ],
    "date": "2012-12-31"
  },
  {
    "domains": [
      {
        "play_count": 21,
        "domain": "example1.com"
      },
      {
        "play_count": 14,
        "domain": "example2.com"
      },
    ],
    "date": "2013-01-01"
  },
  ...
]

Per Video

URL Method
https://api.sproutvideo.com/v1/stats/domains/:video_id GET
Response
Name Type Description
domain String The domain on which the plays occured
play_count Integer The total number of plays that occured on that domain
Example
[
  {
    "play_count": 9743,
    "domain": "example1.com"
  },
  {
    "play_count": 1547,
    "domain": "example2.com"
  },
  ...
]

Per Video, By Date

Inputs
Name Required? Type Description
start_date Optional date The beginning of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
start_date Optional date The end of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data
domains Array An array of domains and their play counts for that particular date
Example
[
  {
    "domains": [
      {
        "play_count": 11,
        "domain": "example1.com"
      },
      {
        "play_count": 5,
        "domain": "example2.com"
      }
    ],
    "date": "2012-12-31"
  },
  {
    "domains": [
      {
        "play_count": 21,
        "domain": "example1.com"
      },
      {
        "play_count": 14,
        "domain": "example2.com"
      },
    ],
    "date": "2013-01-01"
  },
  ...
]

Geo

URL Method
https://api.sproutvideo.com/v1/stats/geo GET

Overall

We collect geographic data on both a country and city level. Calling the geo API method will return the top level country data. To receive city data, pass in the two letter country code for the country for which you'd like to receive data.

Inputs
Name Required? Type Description
country Optional String The two letter ISO 3166-1 alpha-2 code (e.g. US, CA) for a country to receive city data for that country.
Response
Name Type Description
country String The two letter ISO 3166-1 alpha-2 code (e.g. US, CA) for the country in which the plays took place.
city String The city in which the plays took place.
play_count Integer The total number of plays that occured on that country or city
Example
Country
[
  {
    "play_count": 73,
    "country": "US"
  },
  {
    "play_count": 3,
    "country": "CA"
  },
  ...
]
City
[
  {
    "play_count": 17,
    "city": "San Francisco, CA"
  },
  {
    "play_count": 12,
    "city": "New York, NY"
  },
  ...
]

Overall, by date

Inputs
Name Required? Type Description
country Optional String The two letter ISO 3166-1 alpha-2 code (e.g. US, CA) for a country to receive city data for that country.
start_date Optional date The beginning of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
start_date Optional date The end of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data.
geo Array An array of countries or cities and the number of plays that occured there on that particular date
Example
Country
[
  {
    "date": "2012-12-31",
    "geo": [
      {
        "play_count": 787,
        "country": "US"
      },
      {
        "play_count": 95,
        "country": "CA"
      },
      ...
    ]
  },
  {
    "date": "2013-01-01",
    "geo": [
      {
        "play_count": 696,
        "country": "US"
      },
      {
        "play_count": 92,
        "country": "CA"
      },
      ...
    ]
  }
]
City
[
  {
    "date": "2012-12-31",
    "geo": [
      {
        "city": "New York, NY",
        "play_count": 41
      },
      {
        "city": "Chicago, IL",
        "play_count": 35
      },
      ...
    ]
  },
  {
    "date": "2013-01-01",
    "geo": [
      {
        "city": "New York, NY",
        "play_count": 36
      },
      {
        "city": "Allston, MA",
        "play_count": 22
      },
      ...
    ]
  }
]

Per Video

URL Method
https://api.sproutvideo.com/v1/stats/geo/:video_id GET
Inputs
Name Required? Type Description
country Optional String The two letter ISO 3166-1 alpha-2 code (e.g. US, CA) for a country to receive city data for that country.
Response
Name Type Description
country String The two letter ISO 3166-1 alpha-2 code (e.g. US, CA) for the country in which the plays took place.
city String The city in which the plays took place.
play_count Integer The total number of plays that occured on that country or city.
Example
Country
[
  {
    "play_count": 73,
    "country": "US"
  },
  {
    "play_count": 3,
    "country": "CA"
  },
  ...
]
City
[
  {
    "play_count": 17,
    "city": "San Francisco, CA"
  },
  {
    "play_count": 12,
    "city": "New York, NY"
  },
  ...
]

Per Video, By Date

Inputs
Name Required? Type Description
country Optional String The two letter ISO 3166-1 alpha-2 code (e.g. US, CA) for a country to receive city data for that country.
start_date Optional date The beginning of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
start_date Optional date The end of the date range for which you would like to receive data. Dates should be in the format of '2013-04-15' (April 15, 2013).
Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data.
geo Array An array of countries or cities and the number of plays that occured there on that particular date
Example
Country
[
  {
    "date": "2012-12-31",
    "geo": [
      {
        "play_count": 787,
        "country": "US"
      },
      {
        "play_count": 95,
        "country": "CA"
      },
      ...
    ]
  },
  {
    "date": "2013-01-01",
    "geo": [
      {
        "play_count": 696,
        "country": "US"
      },
      {
        "play_count": 92,
        "country": "CA"
      },
      ...
    ]
  }
]
City
[
  {
    "date": "2012-12-31",
    "geo": [
      {
        "city": "New York, NY",
        "play_count": 41
      },
      {
        "city": "Chicago, IL",
        "play_count": 35
      },
      ...
    ]
  },
  {
    "date": "2013-01-01",
    "geo": [
      {
        "city": "New York, NY",
        "play_count": 36
      },
      {
        "city": "Allston, MA",
        "play_count": 22
      },
      ...
    ]
  }
]

Video Types

Overall

URL Method
https://api.sproutvideo.com/v1/stats/video_types GET
Response
Name Type Description
video_type String The type of video that received these plays.
play_count Integer The total number of plays that occured for that video type.
Example
[
  {
    "video_type": "Standard Definition",
    "play_count": 15793
  },
  {
    "video_type": "High Definition",
    "play_count": 520
  }
]

Overall, By Date

Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data.
video_types Array An array of video_types and the number of plays that occured for that type on that particular date
Example
[
  {
    "date": "2012-12-31",
    "video_types": [
      {
        "video_type": "Standard Definition",
        "play_count": 21
      },
      {
        "video_type": "High Definition",
        "play_count": 0
      }
    ]
  },
  {
    "date": "2013-01-01",
    "video_types": [
      {
        "video_type": "Standard Definition",
        "play_count": 41
      },
      {
        "video_type": "High Definition",
        "play_count": 1
      }
    ]
  },
  ...
]

Per Video

URL Method
https://api.sproutvideo.com/v1/stats/video_types/:video_id GET
Response
Name Type Description
video_type String The type of video that received these plays.
play_count Integer The total number of plays that occured for that video type.
Example
[
  {
    "video_type": "Standard Definition",
    "play_count": 15793
  },
  {
    "video_type": "High Definition",
    "play_count": 520
  }
]

Per Video, By Date

Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data.
video_types Array An array of video_types and the number of plays that occured for that type on that particular date
Example
[
  {
    "date": "2012-12-31",
    "video_types": [
      {
        "video_type": "Standard Definition",
        "play_count": 21
      },
      {
        "video_type": "High Definition",
        "play_count": 0
      }
    ]
  },
  {
    "date": "2013-01-01",
    "video_types": [
      {
        "video_type": "Standard Definition",
        "play_count": 41
      },
      {
        "video_type": "High Definition",
        "play_count": 1
      }
    ]
  },
  ...
]

Playback Types

Overall

URL Method
https://api.sproutvideo.com/v1/stats/playback_types GET
Response
Name Type Description
playback_type String The playback method used to play this video. Usually HTML 5 or Adobe Flash.
play_count Integer The total number of plays that occured using that playback method.
Example
[
  {
    "playback_type": "Flash",
    "play_count": 9729
  },
  {
    "playback_type": "HTML5",
    "play_count": 330
  }
]

Overall, By Date

Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data.
playback_types Array An array of playback types and the number of plays that occured for that type on that particular date
Example
[
  {
    "date": "2012-12-31",
    "playback_types": [
      {
        "playback_type": "Flash",
        "play_count": 15
      },
      {
        "playback_type": "HTML5",
        "play_count": 2
      }
    ]
  },
  {
    "date": "2013-01-01",
    "playback_types": [
      {
        "playback_type": "Flash",
        "play_count": 34
      },
      {
        "playback_type": "HTML5",
        "play_count": 5
      }
    ]
  },
  ...
]

Per Video

URL Method
https://api.sproutvideo.com/v1/stats/playback_types/:video_id GET
Response
Name Type Description
playback_type String The playback method used to play this video. Usually HTML 5 or Adobe Flash.
play_count Integer The total number of plays that occured using that playback method.
Example
[
  {
    "playback_type": "Flash",
    "play_count": 9729
  },
  {
    "playback_type": "HTML5",
    "play_count": 330
  }
]

Per Video, By Date

Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data.
playback_types Array An array of playback types and the number of plays that occured for that type on that particular date
Example
[
  {
    "date": "2012-12-31",
    "playback_types": [
      {
        "playback_type": "Flash",
        "play_count": 15
      },
      {
        "playback_type": "HTML5",
        "play_count": 2
      }
    ]
  },
  {
    "date": "2013-01-01",
    "playback_types": [
      {
        "playback_type": "Flash",
        "play_count": 34
      },
      {
        "playback_type": "HTML5",
        "play_count": 5
      }
    ]
  },
  ...
]

Device Types

Overall

URL Method
https://api.sproutvideo.com/v1/stats/device_types GET
Response
Name Type Description
device_type String The type of device used to play this video.
play_count Integer The total number of plays that occured using that type of device.
Example
[
  {
    "play_count": 9293,
    "device_type": "Desktop"
  },
  {
    "play_count": 336,
    "device_type": "Mobile"
  },
  {
    "play_count": 4,
    "device_type": "Game Console"
  },
  ...
]

Overall, By Date

Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data.
device_types Array An array of device types and the number of plays that occured for that type on that particular date
Example
[
  {
    "date": "2012-12-31",
    "device_types": [
      {
        "play_count": 19,
        "device_type": "Desktop"
      },
      {
        "play_count": 2,
        "device_type": "Mobile"
      }
    ]
  },
  {
    "date": "2013-01-01",
    "device_types": [
      {
        "play_count": 37,
        "device_type": "Desktop"
      },
      {
        "play_count": 5,
        "device_type": "Mobile"
      }
    ]
  },
  ...
]

Per Video

URL Method
https://api.sproutvideo.com/v1/stats/device_types/:video_id GET
Response
Name Type Description
device_type String The type of device used to play this video.
play_count Integer The total number of plays that occured using that type of device.
Example
[
  {
    "play_count": 9293,
    "device_type": "Desktop"
  },
  {
    "play_count": 336,
    "device_type": "Mobile"
  },
  {
    "play_count": 4,
    "device_type": "Game Console"
  },
  ...
]

Per Video, By Date

Response
The response will be an array of object which represent the data for each day:
Name Type Description
date String The date for this particular set of data.
device_types Array An array of device types and the number of plays that occured for that type on that particular date
Example
[
  {
    "date": "2012-12-31",
    "device_types": [
      {
        "play_count": 19,
        "device_type": "Desktop"
      },
      {
        "play_count": 2,
        "device_type": "Mobile"
      }
    ]
  },
  {
    "date": "2013-01-01",
    "device_types": [
      {
        "play_count": 37,
        "device_type": "Desktop"
      },
      {
        "play_count": 5,
        "device_type": "Mobile"
      }
    ]
  },
  ...
]