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

There are two ways to authenticate calls to SproutVideo's APIs: OAuth and API keys.

OAuth

To learn more about OAuth 2.0 please read OAuth 2 Simplified by Aaron Parecki.

Registration

To use OAuth, you must first register your application with SproutVideo. You can do this by visiting the OAuth Apps page in your account settings.

Authorization

Once you have registered your application, you will need to request authorization from the user. You can do this by redirecting the user to the following URL: https://sproutvideo.com/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI

After the user has authorized your application, they will be redirected to the URL you specified in the redirect_uri parameter. The URL will contain a code parameter that you can use to request an access token.

Access Token

You can request an access token by making a POST request to https://sproutvideo.com/oauth/token with the following parameters:

Parameter Description
grant_type authorization_code
code The authorization code you received from the user.
redirect_uri The redirect URI you specified when you registered your application.
client_id The client ID you received when you registered your application.
client_secret The client secret you received when you registered your application.

You will receive a JSON response with the following fields:

Field Description
access_token The access token you will use to make API calls.
token_type bearer
expires_in The number of seconds until the access token expires.
refresh_token The refresh token you will use to obtain a new access token when the current one expires.

You can now use the access token to make API calls. To do this, you must include the access token in the Authorization header of your request. The value of the header should be Bearer followed by a space and then the access token.

Refresh Token
Note: SproutVideo issues a new refresh token with every access token refresh response. The previous refresh token will no longer be valid.

When your access token expires, you can use the refresh token to obtain a new access token. To do this, you must make a POST request to https://sproutvideo.com/oauth/token with the following parameters:

Parameter Description
grant_type refresh_token
refresh_token The refresh token you received when you requested an access token.
client_id The client ID you received when you registered your application.
client_secret The client secret you received when you registered your application.
Revoke Token

You can revoke an access token or refresh token by making a POST request to https://sproutvideo.com/oauth/revoke with the following parameters:

Parameter Description
token The access token or refresh token you want to revoke.
client_id The client ID you received when you registered your application.
client_secret The client secret you received when you registered your application.
token_type_hint (optional) access_token or refresh_token depending on the type of token you are revoking.
Introspect Token

You can check the status of an access token or refresh token by making a POST request to https://sproutvideo.com/oauth/introspect with the following parameters:

Parameter Description
token The access token or refresh token you want to check.
client_id The client ID you received when you registered your application.
client_secret The client secret you received when you registered your application.
token_type_hint (optional) access_token or refresh_token depending on the type of token you are checking.

API Key

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 Description
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 200 requests per minute. If there are more than 200 requests in a minute for a particular account, the service will respond with HTTP error 429.

The returned HTTP headers of any API request show your current rate limit status:

Header Name Description
X-RateLimit-Limit The maximum number of requests you're permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

Videos

Note: Embed codes will not be usable until the video state is deployed
Note: If you plan on using the video files returned in the assets hash, you'll need to enable API File Access on your account. Doing so enables the URLS but there are some security implications to consider. If API File Access is enabled, anyone with access to those URLs will have unrestricted ability to download your video. You can enable this setting here: https://sproutvideo.com/settings/api.

Video Privacy

Videos on SproutVideo can have one of several different 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 This 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 optimal 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
folder_id Optional String Retrieve only the videos in the folder specified by this folder id. Example: https://api.sproutvideo.com/v1/videos?folder_id=709df9
playlist_id Optional String Retrieve only the videos in the playlist specified by this playlist id. Example: https://api.sproutvideo.com/v1/videos?playlist_id=97d7eab2c1dd

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": "https://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",
      "plays": 348,
      "title": "example.mov",
      "source_video_file_size": 0,
      "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='https://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></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": {
          "240p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/240.mp4",
          "360p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/360.mp4",
          "480p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/480.mp4",
          "720p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/720.mp4",
          "1080p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4",
          "2k": null,
          "4k": null,
          "8k": null,
          "source": null
        },
        "thumbnails": [
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0000.jpg",
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0001.jpg",
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0002.jpg",
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0003.jpg",
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0004.jpg",
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0005.jpg"
        ],
        "poster_frames": [
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0000.jpg",
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0001.jpg",
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0002.jpg",
          "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0003.jpg"
        ],
        "poster_frame_mp4": null,
        "timeline_images": [
          "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/timeline_0000.jpg"
        ],
        "hls_manifest": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/index.m3u8"
      },
      "download_sd": null,
      "download_hd": null,
      "download_source": null,
      "allowed_domains": null,
      "allowed_ips": null,
      "player_social_sharing": null,
      "player_embed_sharing": null,
      "require_email": false,
      "require_name": false,
      "hide_on_site": false,
      "folder_id": null,
      "airplay_support": null,
      "session_watermarks": null,
      "direct_file_access": null
    },
    ...
  }

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
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 occurred
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. The account-wide setting will be used if this is null
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
240p String The url for the 240p version of this video if it exists
360p String The url for the 360p version of this video if it exists
480p String The url for the 480p version of this video if it exists
720p String The url for the 720p version of this video if it exists
1080p String The url for the 1080p version of this video if it exists
2k String The url for the 2k version of this video if it exists
4k String The url for the 4k version of this video if it exists
8k String The url for the 8k version of this video if it exists
source String The url for the source version of this video if it exists
poster_frame_mp4 String The url for the poster frame mp4 if it exists
timeline_images Array An array of URLs for the timeline images for this video
hls_manifest String The url for the HLS manifest for this video if it exists
download_sd Boolean If this is set to true, viewers will be able to download a standard definition version of your videos. The account-wide setting will be used if this is null
download_hd Boolean If this is set to true, viewers will be able to download a high definition version of your videos. The account-wide setting will be used if this is null
download_source Boolean If this is set to true, and you have enabled source storage on your account, viewers will be able to download the originally uploaded version of your videos. The account-wide setting will be used if this is null
allowed_domains String A comma separated list of domains on which is used as a whitelist for where your embedded videos can play. Click here for more information about this setting. The account-wide setting will be used if this is null
allowed_ips String A comma separated list of ip addresses or ranges which are authorized to view your videos. Click here for more information about this setting. The account-wide setting will be used if this is null
player_social_sharing Boolean If this is set to true, the video player will provide social sharing tools for your viewers. The account-wide setting will be used if this is null
player_embed_sharing Boolean If this is set to true, the video player will allow viewers to copy your video's embed code. The account-wide setting will be used if this is null
require_email Boolean If this is set to true, the video player will require the viewer to enter an email address before watching the video.
require_name Boolean If this is set to true, and require_email is also set to true, the video player will require the viewer to enter a first and last name, in addition to the email address, before watching the video.
hide_on_site Boolean If this is set to true, the video will not be displayed in any listings on your SproutVideo video website. The video can still be accessed using a direct link, however
folder_id String The id of the folder in which this video resides.
airplay_support Boolean If this is set to true, the video player will allow viewers to AirPlay the video to an Apple TV. The account-wide setting will be used if this is null
session_watermarks Boolean If this is set to true, and the subscription plan for your account supports it, the video player will display a watermark when the video is playing. The account-wide setting will be used if this is null
direct_file_access Boolean If this is set to true, you'll be able to access video files directly for use outside of our player without the need for a signed URL. The account-wide setting will be used if this is null

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",
  "plays": 348,
  "title": "example.mov",
  "source_video_file_size": 0,
  "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='https://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></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": {
      "240p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/240.mp4",
      "360p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/360.mp4",
      "480p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/480.mp4",
      "720p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/720.mp4",
      "1080p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4",
      "2k": null,
      "4k": null,
      "8k": null,
      "source": null
    },
    "thumbnails": [
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0000.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0001.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0002.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0003.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0004.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0005.jpg"
    ],
    "poster_frames": [
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0000.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0001.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0002.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0003.jpg"
    ],
    "poster_frame_mp4": null,
    "timeline_images": [
      "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/timeline_0000.jpg"
    ],
    "hls_manifest": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/index.m3u8"
  },
  "download_sd": null,
  "download_hd": null,
  "download_source": null,
  "allowed_domains": null,
  "allowed_ips": null,
  "player_social_sharing": null,
  "player_embed_sharing": null,
  "require_email": false,
  "require_name": false,
  "hide_on_site": false,
  "folder_id": null,
  "airplay_support": null,
  "session_watermarks": null,
  "direct_file_access": null
}

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.
Please note: the maximum file size for source_video is 5GB.
source_video_url Optional String A publicly accessible URL to a video file.
Please note: do not pass in source_video if source_video_url is used.
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 The account-wide setting will be used if this isn't set on a per-video basis.
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.
download_sd Optional Boolean If this is set to true, viewers will be able to download a standard definition version of your videos. The account-wide setting will be used if this isn't set on a per-video basis
download_hd Optional Boolean If this is set to true, viewers will be able to download a high definition version of your videos. The account-wide setting will be used if this isn't set on a per-video basis
download_source Optional Boolean If this is set to true, and you have enabled source storage on your account, viewers will be able to download the originally uploaded version of your videos. The account-wide setting will be used if this isn't set on a per-video basis
allowed_domains Optional String A comma separated list of domains on which is used as a whitelist for where your embedded videos can play. Click here for more information about this setting. The account-wide setting will be used if this isn't set on a per-video basis
allowed_ips Optional String A comma separated list of ip addresses or ranges which are authorized to view your videos. Click here for more information about this setting. The account-wide setting will be used if this isn't set on a per-video basis
player_social_sharing Optional Boolean If this is set to true, the video player will provide social sharing tools for your viewers. The account-wide setting will be used if this isn't set on a per-video basis
player_embed_sharing Optional Boolean If this is set to true, the video player will allow viewers to copy your video's embed code. The account-wide setting will be used if this isn't set on a per-video basis
require_email Optional Boolean If this is set to true, the video player will require the viewer to enter an email address before watching the video.
require_name Optional Boolean If this is set to true, and require_email is also set to true, the video player will require the viewer to enter a first and last name, in addition to the email address, before watching the video.
hide_on_site Optional Boolean If this is set to true, the video will not be displayed in any listings on your SproutVideo video website. The video can still be accessed using a direct link, however
folder_id Optional String The folder in which to place this video.
airplay_support Optional Boolean If this is set to true, the video player will allow viewers to AirPlay the video to an Apple TV. The account-wide setting will be used if this isn't set on a per-video basis
session_watermarks Optional Boolean If this is set to true, and the subscription plan for your account supports it, the video player will display a watermark when the video is playing. The account-wide setting will be used if this isn't set on a per-video basis.
direct_file_access Optional Boolean If this is set to true, you'll be able to access video files directly for use outside of our player without the need for a signed URL. The account-wide setting will be used if this isn't set on a per-video basis.

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",
  "plays": 0,
  "title": "new upload.mov",
  "source_video_file_size": 0,
  "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='https://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></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": {
      "240p": null,
      "360p": null,
      "480p": null,
      "720p": null,
      "1080p": null,
      "2k": null,
      "4k": null,
      "8k": null,
      "source": null
    },
    "thumbnails": [],
    "poster_frames": []
  },
  "download_sd": null,
  "download_hd": null,
  "download_source": null,
  "allowed_domains": null,
  "allowed_ips": null,
  "player_social_sharing": null,
  "player_embed_sharing": null,
  "require_email": false,
  "require_name": false,
  "hide_on_site": false,
  "folder_id": null,
  "airplay_support": null,
  "session_watermarks": null,
  "direct_file_access": null
}

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 Required? 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.
allowed_inputs Optional Array of Strings By default, all inputs are accepted. You can limit which inputs are allowed by passing in a array of input names you'd like us to allow. Any input not in this list will be ignored.
preset_values Optional Object You can pre-fill the values of certain inputs by passing in a hash of input names and values. The input names should be the same as the input names and the values should be the same as the input values. Any input in this list will overwrite anything passed in during the upload.

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",
  "allowed_inputs": [],
  "preset_values": {}
}

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. Set this to null to use the account-wide setting instead
embedded_url Optional String The URL where the video is embedded. This is used for Video Sitemaps.
download_sd Optional Boolean If this is set to true, viewers will be able to download a standard definition version of your videos. Set this to null to use the account-wide setting instead
download_hd Optional Boolean If this is set to true, viewers will be able to download a high definition version of your videos. Set this to null to use the account-wide setting instead
download_source Optional Boolean If this is set to true, and you have enabled source storage on your account, viewers will be able to download the originally uploaded version of your videos. Set this to null to use the account-wide setting instead
allowed_domains Optional String A comma separated list of domains on which is used as a whitelist for where your embedded videos can play. Click here for more information about this setting. Set this to null to use the account-wide setting instead
allowed_ips Optional String A comma separated list of ip addresses or ranges which are authorized to view your videos. Click here for more information about this setting. Set this to null to use the account-wide setting instead
player_social_sharing Optional Boolean If this is set to true, the video player will provide social sharing tools for your viewers. Set this to null to use the account-wide setting instead
player_embed_sharing Optional Boolean If this is set to true, the video player will allow viewers to copy your video's embed code. Set this to null to use the account-wide setting instead
require_email Optional Boolean If this is set to true, the video player will require the viewer to enter an email address before watching the video.
require_name Optional Boolean If this is set to true, and require_email is also set to true, the video player will require the viewer to enter a first and last name, in addition to the email address, before watching the video.
hide_on_site Optional Boolean If this is set to true, the video will not be displayed in any listings on your SproutVideo video website. The video can still be accessed using a direct link, however
folder_id Optional String The folder in which to place this video.
airplay_support Optional Boolean If this is set to true, the video player will allow viewers to AirPlay the video to an Apple TV. Set this to null to use the account-wide setting instead
session_watermarks Optional Boolean If this is set to true, and the subscription plan for your account supports it, the video player will display watermarks when the video is playing. Set this to null to use the account-wide setting instead
direct_file_access Optional Boolean If this is set to true, you'll be able to access video files directly for use outside of our player without the need for a signed URL. Set this to null to use the account-wide setting instead

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",
  "plays": 348,
  "title": "An amazing video",
  "source_video_file_size": 0,
  "embed_code": "<iframe class='sproutvideo-player' type='text/html' src='https://videos.sproutvideo.com/embed/a098d2bbd33e1c328/7ca00d6d622a8e8d' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></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": {
      "240p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/240.mp4",
      "360p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/360.mp4",
      "480p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/480.mp4",
      "720p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/720.mp4",
      "1080p": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/1080.mp4",
      "2k": null,
      "4k": null,
      "8k": null,
      "source": null
    },
    "thumbnails": [
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0000.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0001.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0002.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0003.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0004.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/thumbnails/frame_0005.jpg"
    ],
    "poster_frames": [
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0000.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0001.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0002.jpg",
      "https://images.sproutvideo.com/3d5944db5f967420e4ab256c39b5/d2746e08d99b1da272bc4f553d/poster_frames/frame_0003.jpg"
    ],
    "poster_frame_mp4": null,
    "timeline_images": [
      "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/timeline_0000.jpg"
    ],
    "hls_manifest": "https://api-files.sproutvideo.com/file/a098d2bbd33e1c328/7ca00d6d622a8e8d/index.m3u8"
  },
  "download_sd": null,
  "download_hd": null,
  "download_source": null,
  "allowed_domains": null,
  "allowed_ips": null,
  "player_social_sharing": null,
  "player_embed_sharing": null,
  "require_email": false,
  "require_name": false,
  "hide_on_site": false,
  "folder_id": null,
  "airplay_support": null,
  "session_watermarks": null,
  "direct_file_access": null
}

Replace a video

URL Method
https://api.sproutvideo.com/v1/videos/:id/replace 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
Please note: the maximum file size for source_video is 5GB.
source_video_url Optional String A publicly accessible URL to a video file.
Please note: do not pass in source_video if source_video_url is used.

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.

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 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, png, gif, and mp4 files. MP4s must be no longer than 8 seconds in duration and no greater than 720p in resolution.
Poster frames must be under 500 kilobytes for jpg and png and 10 megabytes for gifs and mp4s. You will receive a response code of 413 - Request Entity Too Large if the file you upload is larger than those limits.

Inputs

Name Required? Type Description
custom_poster_frame Required image or mp4 The actual contents of the poster frame to be uploaded. (Must be under 500 kilobytes for JPG and PNG and 10 megabytes for GIFs and MP4s)

Response

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

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.

Subtitles

List subtitles for a video

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

Inputs

Name Required? Type Description
order_by Optional String Order the results by one of the following: created_at, updated_at, language, title. Example: https://api.sproutvideo.com/v1/videos/a098d2bbd33e1c328/subtitles?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/a098d2bbd33e1c328/subtitles?order_by=updated_at&order_dir=desc
language Optional String Only display results with the specified language. Must be an ISO 639-1 language code. Example: https://api.sproutvideo.com/v1/videos/a098d2bbd33e1c328/subtitles?language=en

Response

Name Type Description
total Integer The total number of subtitles 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)
subtitles Array An array containing subtitle objects. See the response of getting a single subtitle for the items in a subtitle.

Example

{
  total: 2,
  subtitles: [
    {
      "id": "bd8b51d1",
      "language": "en",
      "language_description": "English",
      "content": "...",
      "created_at": "2012-09-27T13:13:50-10:00",
      "updated_at": "2012-09-27T13:13:51-10:00"
    },
    {
      "id": "51d18e6c",
      "language": "de",
      "language_description": "German",
      "content": "..."
      "created_at": "2012-09-27T13:14:27-10:00",
      "updated_at": "2012-09-27T13:14:28-10:00"
    },
    ...
  ]
}

Get a single Subtitle

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

Response

Name Type Description
id String The id of the subtitle
language String The ISO 639-1 language code of the subtitle.
language_description String The full name of the language of the subtitle.
content String The subtitle content in WebVTT format.
created_at String The date on which this subtitle was created.
updated_at String The date on which this subtitle was last edited.

Example

{
  "id": "51d18e6c",
  "language": "en",
  "language_description": "English",
  "content": "...",
  "created_at": "2012-09-27T13:13:50-10:00",
  "updated_at": "2012-09-27T13:13:51-10:00"
}

Create a new subtitle

URL Method
https://api.sproutvideo.com/v1/videos/:video_id/subtitles POST

Inputs

Name Required? Type Description
language Required String The ISO 639-1 language code of the subtitle.
content Required String The subtitle content in WebVTT format.

Response

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

Example

Request
{
  "language": "en",
  "content": "WEBVTT FILE..."
}
Response
{
  "id": "51d18e6c",
  "language": "en",
  "language_description" : "English",
  "content": "WEBVTT FILE...",
  "created_at": "2012-09-27T13:14:27-10:00",
  "updated_at": "2012-09-27T13:14:28-10:00"
}

Edit a Subtitle

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

Inputs

Name Required? Type Description
language Optional String The ISO 639-1 language code of the subtitle.
content Optional String The subtitle content in WebVTT format.

Response

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

Example

Request
{
  "language": "de"
}
Response
{
  "id": "51d18e6c",
  "language": "de",
  "language_description" : "German",
  "content": "WEBVTT FILE...",
  "created_at": "2012-09-27T13:14:27-10:00",
  "updated_at": "2012-08-09T10:19:08-10:00"
}

Delete a Subtitle

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

Response

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

Calls to Action

List calls to action for a video

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

Response

Name Type Description
total Integer The total number of calls to action for the video
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)
calls_to_action Array An array containing calls to action objects. See the response of getting a single call to action for the items in a call to action.

Example

{
  total: 1,
  calls_to_action: [
    {
      id: 'bd8b51d1',
      text: 'This is a call to action',
      url: 'https://sproutvideo.com',
      start_time: 0.0,
      end_time: 5.0
    }
  ]
}

Get a single Call to Action

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

Response

Name Type Description
id String The id of the call to action.
text String The text to be displayed for your call to action.
url String The full URL where your viewer will be directed when clicking on your call to action.
start_time Float The time, in seconds, when your call to action will begin displaying.
end_time Float The time, in seconds, at which your call to action will stop displaying.
created_at String The date on which this call to action was created.
updated_at String The date on which this call to action was last edited.

Example

{
  "id": "51d18e6c",
  "text": "This is a call to action",
  "url": "https://sproutvideo.com",
  "start_time": 0.0,
  "end_time": 5.0,
  "created_at": "2012-09-27T13:13:50-10:00",
  "updated_at": "2012-09-27T13:13:51-10:00"
}

Create a new Call to Action

URL Method
https://api.sproutvideo.com/v1/videos/:video_id/calls_to_action POST

Inputs

Name Required? Type Description
text Required String The text to be displayed for your call to action.
url Required String The full URL where your viewer will be directed when clicking on your call to action.
start_time Required Float The time, in seconds, when your call to action will begin displaying.
end_time Required Float The time, in seconds, at which your call to action will stop displaying.

Response

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

Example

Request
{
  "text": "This is a all to action",
  "url": "https://sproutvideo.com",
  "start_time": 0.0,
  "end_time": 5.0
}
Response
{
  "id": "51d18e6c",
  "text": "This is a call to action",
  "url": "https://sproutvideo.com",
  "start_time": 0.0,
  "end_time": 5.0,
  "created_at": "2012-09-27T13:13:50-10:00",
  "updated_at": "2012-09-27T13:13:50-10:00",
}

Edit a Call to Action

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

Inputs

Name Required? Type Description
text Optional String The text to be displayed for your call to action.
url Optional String The full URL where your viewer will be directed when clicking on your call to action.
start_time Optional Float The time, in seconds, when your call to action will begin displaying.
end_time Optional The time, in seconds, at which your call to action will stop displaying.

Response

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

Example

Request
{
  "text": "This is an updated call to action",
  "end_time": 9.5
}
Response
{
  "id": "51d18e6c",
  "text": "This is an updated call to action",
  "url": "https://sproutvideo.com",
  "start_time": 0.0,
  "end_time": 9.5,
  "created_at": "2012-09-27T13:13:50-10:00",
  "updated_at": "2012-09-27T13:15:50-10:00",
}

Delete a Call to Action

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

Response

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

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",
      "description": "A playlist of movie trailers",
      "security_token": "9c4afc572c2af416",
      "videos": [
        "8b19c6e1560e8da1c2",
        "21a0c9b6ec18ed6815",
        "a02e18cdeb566c1198",
        "081c261c1d5b6e9ae8",
        "a15ee061d288c9c16b",
        "5ce81a011d6b9286ce"
      ],
      "id": "e210c6ad6b1ec88591",
      "embed_code": "<iframe class='sproutvideo-playlist' type='text/html' src='https://videos.sproutvideo.com/playlist/e210c6ad6b1ec88591/9c4afc572c2af416' width='918' height='360' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></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
description String The description of the playlist
requires_signed_embeds Boolean Indicates if signed embed codes are required for this video. The account-wide setting will be used if this is null
prefers_embed_password Boolean If the privacy value is set to 1 and there is a password set for the playlist, setting prefers_embed_password to true will require a viewer to enter the password before being able to watch the playlist. Setting prefers_embed_password to false will make the playlist not require a password before being able to view 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",
  "description": "A playlist of movie trailers",
  "requires_signed_embeds": null,
  "prefers_embed_password": false,
  "security_token": "9c4afc572c2af416",
  "videos": [
    "8b19c6e1560e8da1c2",
    "21a0c9b6ec18ed6815",
    "a02e18cdeb566c1198",
    "081c261c1d5b6e9ae8",
    "a15ee061d288c9c16b",
    "5ce81a011d6b9286ce"
  ],
  "id": "e210c6ad6b1ec88591",
  "embed_code": "<iframe class='sproutvideo-playlist' type='text/html' src='https://videos.sproutvideo.com/playlist/e210c6ad6b1ec88591/9c4afc572c2af416' width='918' height='360' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></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
description Optional String the description of the playlist
requires_signed_embeds Optional Boolean Indicates if signed embed codes are required for this playlist. The account-wide setting will be used if this isn't set on a per-playlist basis.
prefers_embed_password Optional Boolean If the privacy value is set to 1 and there is a password set for the playlist, setting prefers_embed_password to true will require a viewer to enter the password before being able to watch the playlist. Setting prefers_embed_password to false will make the playlist not require a password before being able to view 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 time. 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",
  "description": null,
  "requires_signed_embeds": null,
  "prefers_embed_password": false,
  "security_token": "9c4afc572c2af416",
  "videos": [
    "21a0c9b6ec18ed6815",
    "8b19c6e1560e8da1c2",
    "5ce81a011d6b9286ce",
    "081c261c1d5b6e9ae8"
  ],
  "id": "e210c6ad6b1ec88591",
  "embed_code": "<iframe class='sproutvideo-playlist' type='text/html' src='https://videos.sproutvideo.com/playlist/e210c6ad6b1ec88591/9c4afc572c2af416' width='918' height='360' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></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
description Optional String The description of the playlist
requires_signed_embeds Optional Boolean Indicates if signed embed codes are required for this playlist. The account-wide setting will be used if this isn't set on a per-playlist basis.
prefers_embed_password Optional Boolean If the privacy value is set to 1 and there is a password set for the playlist, setting prefers_embed_password to true will require a viewer to enter the password before being able to watch the playlist. Setting prefers_embed_password to false will make the playlist not require a password before being able to view 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 time. 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",
  "description": null,
  "requires_signed_embeds": null,
  "prefers_embed_password": false,
  "security_token": "9c4afc572c2af416",
  "videos": [
    "5ce81a011d6b9286ce",
    "8b19c6e1560e8da1c2",
    "21a0c9b6ec18ed6815",
    "081c261c1d5b6e9ae8"
  ],
  "id": "e210c6ad6b1ec88591",
  "embed_code": "<iframe class='sproutvideo-playlist' type='text/html' src='https://videos.sproutvideo.com/playlist/e210c6ad6b1ec88591/9c4afc572c2af416' width='918' height='360' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></iframe>"
}

Upload a poster frame

URL Method
https://api.sproutvideo.com/v1/playlists/: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 playlist.

Note: This method only accepts input as multipart/form-data, 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, png, gif, and mp4 files. MP4s must be no longer than 8 seconds in duration and no greater than 720p in resolution.
Poster frames must be under 500 kilobytes for jpg and png and 10 megabytes for gifs and mp4s. You will receive a response code of 413 - Request Entity Too Large if the file you upload is larger than those limits.

Inputs

Name Required? Type Description
custom_poster_frame Required image or mp4 The actual contents of the poster frame to be uploaded. (Must be under 500 kilobytes for JPG and PNG and 10 megabytes for GIFs and MP4s)

Response

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

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.

Folders

Folders are a great way to organize videos in a hierarchical way within your account. Folders can contain both videos and other folders.

List your folders

URL Method
https://api.sproutvideo.com/v1/folders 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/folders?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
parent_id Optional String Display all of the folders within a given parent folder specified by the parent_id. Example: https://api.sproutvideo.com/v1/logins?parent_id=06edb9ee

Response

Name Type Description
total Integer The total number of folders in the give folder.
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)
folders Array An array containing folder objects. See the response of getting a single folder for the items in a folder.

Example

{
  "total": 12,
  "next_page": "https://api.sproutvideo.com/v1/folders?page=2&per_page=25",
  "folders": [
    {
      "id": "06edb9ee"
      "name": "My Folder",
      "parent_id": null,
      "created_at": "2010-08-27T01:35:41Z",
      "updated_at": "2011-05-07T21:55:35Z"
    },
    ...
  ]
}

Get a single folder

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

Response

Name Type Description
id String The id of the login
name String The name of the folder
parent_id String The folder in which this folder is located. If parent_id is null, the folder is at the root level.
created_at String The date on which this folder was created
updated_at String The date on which this login was folder edited

Example

{
  "id": "06edb9ee"
  "name": "My Folder"
  "parent_id": null,
  "created_at": "2010-08-27T01:35:41Z",
  "updated_at": "2011-05-07T21:55:35Z",
}

Create a new folder

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

Inputs

Name Required? Type Description
name Required String The name address of the folder
parent_id Optional String The id of the folder in which this new folder should be placed

Response

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

Example

Request
{
  "name": "My Folder"
}
Response
{
  "id": "06edb9ee"          
  "name": "My Folder",
  "parent_id": null,          
  "created_at": "2011-05-07T21:55:35Z",
  "updated_at": "2011-05-07T21:55:35Z"
}

Edit a folder

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

Inputs

Name Required? Type Description
name Optional String The new name for this folder
parent_id Optional String The new parent_id for this folder

Response

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

Example

Request
{
  "name": "My Other Folder"
}
Response
{
  "id": "06edb9ee"
  "name": "My Other Folder",
  "parent_id": null,          
  "created_at": "2010-08-27T01:35:41Z",
  "updated_at": "2011-05-07T21:55:35Z"
}

Delete a folder

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

Inputs

Name Required? Type Description
delete_all Optional boolean To prevent any accidental content loss, deleting a folder will move all of the folder's contents to the root folder by default. To delete all of the contents (folders and videos) contained within a folder, pass the delete_all parameter when making the delete call. Example: https://api.sproutvideo.com/v1/folders/06edb9ee?delete_all=true

Response

The response for this call is the same as the response for getting a single folder. The data for the deleted folder 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 access 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",
      "session_watermarks": false
    },
    ...
  ]
}

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
session_watermarks Boolean If a session watermark should be displayed when the viewer watches the video. This setting overrides any per-video or account-wide settings

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",
  "session_watermarks": false
}

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 Required 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, in ISO8601 format, 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, in ISO8601 format, 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
session_watermarks Optional Boolean If a session watermark should be displayed when the viewer watches the video. This setting overrides any per-video or account-wide settings

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"
  "session_watermarks": true
}
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",
  "session_watermarks": true
}

Bulk create access grants

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

If you need to create multiple access grants at one time, you can use our bulk access grant endpoint. This allows you to create many access grants using a single API request.

Any existing access grants for a video / login combination will be overwritten with the new access grant generated by this call.
Note: The number of access grants may not exceed 100 per request.

Inputs

The input for this endpoint is an array of access grant objects with the following properties

Name Required? Type Description
login_id Required String The id for the login to which you'd like to grant access
video_id Required 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
session_watermarks Optional Boolean If a session watermark should be displayed when the viewer watches the video. This setting overrides any per-video or account-wide settings

Example

Request
[{
  "login_id": "1da5",
  "video_id": "49fc3ee1215b2d89c1",
  "allowed_plays": 5,
  "download_permissions": ["original", "hd"],
  "access_ends_at": "2014-08-03T21:56:03Z"
},{
  "login_id": "5733b1d19accd1",
  "video_id": "49fc3ee1215b2d89c1",
  "allowed_plays": 5,
  "download_permissions": ["original", "hd"],
  "access_ends_at": "2014-08-03T21:56:03Z"
},
...
]
Response

The response will be an array that contains the result of each input item. If any of the input access grant items you passed in were invalid, an error message for that item will be returned instead of the newly generated access grant.

[{
  "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",
	"session_watermarks": false
},{
  "updated_at": "2012-08-03T18:44:33Z",
  "play_count": 1,
  "allowed_plays": 5,
  "access_starts_at": null,
  "login_id": "5733b1d19accd1",
  "access_ends_at": "2014-08-03T21:56:03Z",
  "download_permissions": ["original", "hd"],
  "video_id": "49fc3ee1215b2d89c1",
  "id": "52998a",
  "created_at": "2012-08-03T18:44:33Z",
  "session_watermarks": false
},
...
]

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, in ISO8601 format, 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, in ISO8601 format, 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
session_watermarks Optional Boolean If a session watermark should be displayed when the viewer watches the video. This setting overrides any per-video or account-wide settings

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",
  "session_watermarks": false
}

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 returned.

Live Streams

Live Stream States

Live Streams on SproutVideo can be in one of several different states:

State Description
Idle The live stream is waiting for input from the encoder.
Active This live stream is now "active" and should be playing back in the player at this point.
Recording Recording on this live stream has started. SproutVideo has successfully processed the first frames from the encoder.
Connected An encoder has successfully connected to this live stream.
Disconnected An encoder has disconnected from this live stream.
Ended The live stream has completed.
Archived The video on demand version of the live stream has begun processing and will soon be available for playback.
Failed This live stream encountered an error and is unable to continue.

List your live streams

URL Method
https://api.sproutvideo.com/v1/live_streams 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/live_streams?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/live_streams?order_by=title&order_dir=desc
tag_id Optional String Retrieve only the videos tagged with this tag id. Example: https://api.sproutvideo.com/v1/live_streams?tag_id=a323d32
tag_name Optional String Retrieve only the videos tagged with this tag name. Example: https://api.sproutvideo.com/v1/live_streams?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/live_streams?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/live_streams?state=active
archive_folder_id Optional String Retrieve only the videos in the folder specified by this folder id. Example: https://api.sproutvideo.com/v1/live_streams?archive_folder_id=709df9

Response

Name Type Description
total Integer The total number of live_streams 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)
live_streams Array An array containing live_stream objects. See the response of getting a single live stream for the items in a live stream.

Example

{
  "total": 16,
  "live_streams": [
    {
      "id": "2c4cadd90b",
      "stream_key": "2c2a273e-16ef-d071-6eb0-ff0d97ab3c3",
      "state": "archived",
      "latency": "low",
      "title": "My First Live Stream",
      "description": "My Live Stream Description",
      "created_at": "2022-05-01T16:48:36-04:00",
      "updated_at": "2022-05-02T05:01:06-04:00",
      "archive_live_stream": null,
      "unlist_after_live_stream_ends": null,
      "duration": 190.28,
      "embed_code": "<iframe class='sproutvideo-player' src='https://videos.sproutvideo.com/embed/db04e91c46dc97193c/6090caa41998fe08' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></iframe>",
      "video_uid": "db04e91c46dc97193c",
      "video_security_token": "6090caa41998fe08",
      "privacy": 0,
      "password": null,
      "tags": [ ],
      "requires_signed_embeds": null,
      "selected_poster_frame_number": 1588366164,
      "embedded_url": null,
      "download_sd": null,
      "download_hd": null,
      "download_uhd": null,
      "download_source": null,
      "allowed_domains": null,
      "allowed_ips": null,
      "player_social_sharing": null,
      "player_embed_sharing": null,
      "require_email": false,
      "require_name": false,
      "hide_on_site": false,
      "archive_folder_id": "1d6c66d8b9e8bd15",
      "webhook_url": null,
      "assets": {
        "poster_frames": [
          "https://images.sproutvideo.com/5926a94544bef354e4ddb653b73690cc/b4f1db863fb48796be2f4469291e4adf/poster_frames/frame_1588366164.jpg"
        ]
      }
    },
    ...
  ],
  "next_page": "https://api.sproutvideo.com/v1/live_streams?page=2&per_page=25"
}

Get a single live stream

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

Response

Name Type Description
id String The id of this live stream
stream_key String The stream key to use with your encoder to stream to this live stream
state String The current state of the live stream
latency String The latency for this live stream. Either 'low' or 'standard'
title String The title of this live stream
description String The description for this live stream
created_at String The date at which the live stream was created
updated_at String The date when the last edit to this live stream occurred
archive_live_stream Boolean You may choose to automatically save a recording in your account when your live stream ends
unlist_after_live_stream_ends Boolean Unlist the video on demand version of the live stream after the stream has ended
duration Integer The duration of the live stream in seconds
embed_code String The embed code for this live stream
video_id String The id of the associated video for this live stream
video_security_token String The security token for this live stream's video
privacy String The privacy setting for the live stream
password String The password for this live stream if it is set
tags Array An array of tag ids with which this live stream is tagged
requires_signed_embeds Boolean Indicates if signed embed codes are required for this live stream. The account-wide setting will be used if this is null
selected_poster_frame_number Integer The currently selected poster frame number
embedded_url String The URL where the live stream is embedded. This is used for Video Sitemaps.
download_sd Boolean If this is set to true, viewers will be able to download a standard definition version of your live stream. The account-wide setting will be used if this is null
download_hd Boolean If this is set to true, viewers will be able to download a high definition version of your live stream. The account-wide setting will be used if this is null
download_uhd Boolean If this is set to true, viewers will be able to download an ultra high definition version of your live stream. The account-wide setting will be used if this is null
download_source Boolean If this is set to true, and you have enabled source storage on your account, viewers will be able to download the originally uploaded version of your live stream. The account-wide setting will be used if this is null
allowed_domains String A comma separated list of domains on which is used as a whitelist for where your embedded live stream can play. Click here for more information about this setting. The account-wide setting will be used if this is null
allowed_ips String A comma separated list of ip addresses or ranges which are authorized to view your live stream. Click here for more information about this setting. The account-wide setting will be used if this is null
player_social_sharing Boolean If this is set to true, the video player will provide social sharing tools for your viewers. The account-wide setting will be used if this is null
player_embed_sharing Boolean If this is set to true, the video player will allow viewers to copy your video's embed code. The account-wide setting will be used if this is null
require_email Boolean If this is set to true, the video player will require the viewer to enter an email address before watching the live stream.
require_name Boolean If this is set to true, and require_email is also set to true, the video player will require the viewer to enter a first and last name, in addition to the email address, before watching the live stream.
hide_on_site Boolean If this is set to true, the live stream will not be displayed in any listings on your SproutVideo video website. The live stream can still be accessed using a direct link, however
archive_folder_id String The id of the folder in which the archived version of this live stream will reside.
webhook_url String Whenever the state of the live stream changes, we will attempt an HTTP POST with the JSON metadata about the live stream to the URL specified in this field. The body of the post is the same as the response for getting a single live stream
assets Array An array containing all of the assets associated with the live stream
Name Type Description
poster_frames Array An array of URLS for the poster frame for this live stream

Example

{
  "id": "2c4cadd90b",
  "stream_key": "2c2a273e-16ef-d071-6eb0-ff0d97ab3c3",
  "state": "archived",
  "latency": "low",
  "title": "My First Live Stream",
  "description": "My Live Stream Description",
  "created_at": "2022-05-01T16:48:36-04:00",
  "updated_at": "2022-05-02T05:01:06-04:00",
  "archive_live_stream": null,
  "unlist_after_live_stream_ends": null,
  "duration": 190.28,
  "embed_code": "<iframe class='sproutvideo-player' src='https://videos.sproutvideo.com/embed/db04e91c46dc97193c/6090caa41998fe08' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></iframe>",
  "video_uid": "db04e91c46dc97193c",
  "video_security_token": "6090caa41998fe08",
  "privacy": 0,
  "password": null,
  "tags": [ ],
  "requires_signed_embeds": null,
  "selected_poster_frame_number": 1588366164,
  "embedded_url": null,
  "download_sd": null,
  "download_hd": null,
  "download_uhd": null,
  "download_source": null,
  "allowed_domains": null,
  "allowed_ips": null,
  "player_social_sharing": null,
  "player_embed_sharing": null,
  "require_email": false,
  "require_name": false,
  "hide_on_site": false,
  "archive_folder_id": "1d6c66d8b9e8bd15",
  "webhook_url": null,
  "assets": {
    "poster_frames": [
      "https://images.sproutvideo.com/5926a94544bef354e4ddb653b73690cc/b4f1db863fb48796be2f4469291e4adf/poster_frames/frame_1588366164.jpg"
    ]
  }
}

Create a live stream

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

Inputs

Name Required? Type Description
title Required String The title of the live stream
description Optional String An optional description for the live stream
latency Optional String The latency for this live stream. Either 'low' or 'standard'
archive_live_stream Optional Boolean You may choose to automatically save a recording in your account when your live stream ends
unlist_after_live_stream_ends Optional Boolean Unlist the video on demand version of the live stream after the stream has ended
privacy Optional Integer The privacy setting for the live stream (Defaults to the default value for the account)
password Optional String The password for the live stream if the live stream'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 live stream, setting prefers_embed_password to true will require a viewer to enter the password before being able to watch the live stream. Setting prefers_embed_password to false will make the live stream not require a password before being able to view the live stream.
tags Optional Array of Strings Tags to associate with the live stream. Pass one or more tags ids to add the set of tags to the live stream. Example: ["4a32d29b4c4", "82dbbde97a"]
tag_names Optional Array of Strings Tags to associate with the live stream. Pass on or more tag names to add the set of tags to the live stream. 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"]
webhook_url Optional String Whenever the state of the live stream changes, we will attempt an HTTP POST with the JSON metadata about the live stream to the URL specified in this field. The body of the post is the same as the response for getting a single live stream
requires_signed_embeds Optional Boolean Indicates if signed embed codes are required for this live stream. The account-wide setting will be used if this isn't set on a per-live stream basis.
embedded_url Optional String The URL where the live stream is embedded. This is used for Video Sitemaps.
download_sd Optional Boolean If this is set to true, viewers will be able to download a standard definition version of your live stream. The account-wide setting will be used if this isn't set on a per-live stream basis
download_hd Optional Boolean If this is set to true, viewers will be able to download a high definition version of your live stream. The account-wide setting will be used if this isn't set on a per-live stream basis
download_uhd Optional Boolean If this is set to true, viewers will be able to download a ultra high definition version of your live stream. The account-wide setting will be used if this isn't set on a per-live stream basis
download_source Optional Boolean If this is set to true, and you have enabled source storage on your account, viewers will be able to download the originally uploaded version of your live stream. The account-wide setting will be used if this isn't set on a per-live stream basis
allowed_domains Optional String A comma separated list of domains on which is used as a whitelist for where your embedded live stream can play. Click here for more information about this setting. The account-wide setting will be used if this isn't set on a per-live stream basis
allowed_ips Optional String A comma separated list of ip addresses or ranges which are authorized to view your live stream. Click here for more information about this setting. The account-wide setting will be used if this isn't set on a per-live stream basis
player_social_sharing Optional Boolean If this is set to true, the video player will provide social sharing tools for your viewers. The account-wide setting will be used if this isn't set on a per-live stream basis
player_embed_sharing Optional Boolean If this is set to true, the video player will allow viewers to copy your video's embed code. The account-wide setting will be used if this isn't set on a per-live stream basis
require_email Optional Boolean If this is set to true, the video player will require the viewer to enter an email address before watching the live stream.
require_name Optional Boolean If this is set to true, and require_email is also set to true, the video player will require the viewer to enter a first and last name, in addition to the email address, before watching the live stream.
hide_on_site Optional Boolean If this is set to true, the live stream will not be displayed in any listings on your SproutVideo video website. The live stream can still be accessed using a direct link, however
archive_folder_id Optional String The folder in which to place the video on demand version of this live stream when it is over.

Response

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

Example

Request
{
  "title": "My First Live Stream",
  "description": "My Live Stream Description",
  "latency": "low",
  "archive_folder_id": "1d6c66d8b9e8bd15"
}
Response
{
  "id": "2c4cadd90b",
  "stream_key": "2c2a273e-16ef-d071-6eb0-ff0d97ab3c3",
  "state": "idle",
  "latency": "low",
  "title": "My First Live Stream",
  "description": "My Live Stream Description",
  "created_at": "2022-05-01T16:48:36-04:00",
  "updated_at": "2022-05-01T16:48:36-04:00",
  "archive_live_stream": null,
  "unlist_after_live_stream_ends": null,
  "duration": null,
  "embed_code": "<iframe class='sproutvideo-player' src='https://videos.sproutvideo.com/embed/db04e91c46dc97193c/6090caa41998fe08' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></iframe>",
  "video_uid": "db04e91c46dc97193c",
  "video_security_token": "6090caa41998fe08",
  "privacy": 0,
  "password": null,
  "tags": [ ],
  "requires_signed_embeds": null,
  "selected_poster_frame_number": 0,
  "embedded_url": null,
  "download_sd": null,
  "download_hd": null,
  "download_uhd": null,
  "download_source": null,
  "allowed_domains": null,
  "allowed_ips": null,
  "player_social_sharing": null,
  "player_embed_sharing": null,
  "require_email": false,
  "require_name": false,
  "hide_on_site": false,
  "archive_folder_id": "1d6c66d8b9e8bd15",
  "webhook_url": null,
  "assets": {
    "poster_frames": [
      "https://images.sproutvideo.com/5926a94544bef354e4ddb653b73690cc/b4f1db863fb48796be2f4469291e4adf/poster_frames/frame_0.jpg"
    ]
  }
}

Edit a live stream

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

Inputs

Name Required? Type Description
title Required String The title of the live stream
description Optional String An optional description for the live stream
archive_live_stream Optional Boolean You may choose to automatically save a recording in your account when your live stream ends
unlist_after_live_stream_ends Optional Boolean Unlist the video on demand version of the live stream after the stream has ended
privacy Optional Integer The privacy setting for the live stream (Defaults to the default value for the account)
password Optional String The password for the live stream if the live stream'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 live stream, setting prefers_embed_password to true will require a viewer to enter the password before being able to watch the live stream. Setting prefers_embed_password to false will make the live stream not require a password before being able to view the live stream.
tags Optional Array of Strings Tags to associate with the live stream. Pass one or more tags ids to replace the set of tags on the live stream. Send an empty array [ ] to clear all tags from the live stream. Example: ["4a32d29b4c4", "82dbbde97a"]
tag_names Optional Array of Strings Tags to associate with the live stream. Pass on or more tag names to replace the set of tags on the live stream. Send an empty array [ ] to clear all tags from the live stream. Example: ["Tag One", "Tag Two"]
webhook_url Optional String Whenever the state of the live stream changes, we will attempt an HTTP POST with the JSON metadata about the live stream to the URL specified in this field. The body of the post is the same as the response for getting a single live stream
requires_signed_embeds Optional Boolean Indicates if signed embed codes are required for this live stream. Set this to null to use the account-wide setting instead
embedded_url Optional String The URL where the live stream is embedded. This is used for Video Sitemaps.
download_sd Optional Boolean If this is set to true, viewers will be able to download a standard definition version of your live stream. Set this to null to use the account-wide setting instead
download_hd Optional Boolean If this is set to true, viewers will be able to download a high definition version of your live stream. Set this to null to use the account-wide setting instead
download_uhd Optional Boolean If this is set to true, viewers will be able to download a ultra high definition version of your live stream. Set this to null to use the account-wide setting instead
download_source Optional Boolean If this is set to true, and you have enabled source storage on your account, viewers will be able to download the originally uploaded version of your live stream. Set this to null to use the account-wide setting instead
allowed_domains Optional String A comma separated list of domains on which is used as a whitelist for where your embedded live stream can play. Click here for more information about this setting. Set this to null to use the account-wide setting instead
allowed_ips Optional String A comma separated list of ip addresses or ranges which are authorized to view your live stream. Click here for more information about this setting. Set this to null to use the account-wide setting instead
player_social_sharing Optional Boolean If this is set to true, the video player will provide social sharing tools for your viewers. Set this to null to use the account-wide setting instead
player_embed_sharing Optional Boolean If this is set to true, the video player will allow viewers to copy your video's embed code. Set this to null to use the account-wide setting instead
require_email Optional Boolean If this is set to true, the video player will require the viewer to enter an email address before watching the live stream.
require_name Optional Boolean If this is set to true, and require_email is also set to true, the video player will require the viewer to enter a first and last name, in addition to the email address, before watching the live stream.
hide_on_site Optional Boolean If this is set to true, the live stream will not be displayed in any listings on your SproutVideo video website. The live stream can still be accessed using a direct link, however
archive_folder_id Optional String The folder in which to place the video on demand version of this live stream when it is over.

Example

Request Body
{
  "title":"An updated live stream title",
  "description": "This really is an amazing live stream!",
  "privacy": 1,
  "password": "live stream password",
  "prefers_embed_password": true,
  "tags": ["82dbbde97a"]
}
Response Body
{
  "id": "2c4cadd90b",
  "stream_key": "2c2a273e-16ef-d071-6eb0-ff0d97ab3c3",
  "state": "archived",
  "latency": "low",
  "title": "This really is an amazing live stream!",
  "description": "My Live Stream Description",
  "created_at": "2022-05-01T16:48:36-04:00",
  "updated_at": "2022-05-02T05:01:06-04:00",
  "archive_live_stream": null,
  "unlist_after_live_stream_ends": null,
  "duration": 190.28,
  "embed_code": "<iframe class='sproutvideo-player' src='https://videos.sproutvideo.com/embed/db04e91c46dc97193c/6090caa41998fe08' width='630' height='354' frameborder='0' allowfullscreen referrerpolicy='no-referrer-when-downgrade' title='Video Player'></iframe>",
  "video_uid": "db04e91c46dc97193c",
  "video_security_token": "6090caa41998fe08",
  "privacy": 1,
  "password": "live stream password",
  "tags": ["82dbbde97a"],
  "requires_signed_embeds": null,
  "selected_poster_frame_number": 1588366164,
  "embedded_url": null,
  "download_sd": null,
  "download_hd": null,
  "download_uhd": null,
  "download_source": null,
  "allowed_domains": null,
  "allowed_ips": null,
  "player_social_sharing": null,
  "player_embed_sharing": null,
  "require_email": false,
  "require_name": false,
  "hide_on_site": false,
  "archive_folder_id": "1d6c66d8b9e8bd15",
  "webhook_url": null,
  "assets": {
    "poster_frames": [
      "https://images.sproutvideo.com/5926a94544bef354e4ddb653b73690cc/b4f1db863fb48796be2f4469291e4adf/poster_frames/frame_1588366164.jpg"
    ]
  }
}

Delete a live stream

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

Response

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

End a live stream

URL Method
https://api.sproutvideo.com/v1/live_streams/:id/end_stream POST

Response

The response for this call is the same as the response for getting a single live stream. The live stream will immediately be ended and the encoder will be disconnected.

Analytics

Analytics data may not be available for all accounts. Check the 'Manage Subscription' page within your account settings to verify that your plan includes analytics and/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 unique 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).
end_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 unique 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 unique 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).
end_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 unique 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
  },
  ...
]

Download Counts

Overall

URL Method
https://api.sproutvideo.com/v1/stats/downloads GET
Response
Name Type Description
download_count Integer The total number of downloads across all of your videos
Example
{
  "download_count": 11869,
}

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).
end_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
sd_download_count Integer The total number of times your video was downloaded in SD resolution
hd_download_count Integer The total number of times your videos was downloaded in HD resolution
uhd_download_count Integer The total number of times your video was downloaded in UHD resolution
source_download_count Integer The total number of times your video was downloaded using the originally uploaded video
Example
[
  {
    "date": "2012-12-31",
    "sd_download_count": 12,
    "hd_download_count": 70,
    "uhd_download_count": 6,
    "source_download_count": 187
  },
  {
    "date": "2013-01-01",
    "sd_download_count": 24,
    "hd_download_count": 636,
    "uhd_download_count": 43,
    "source_download_count": 240
  },
  ...
]

Per Video

URL Method
https://api.sproutvideo.com/v1/stats/downloads/:video_id GET
Response
Name Type Description
download_count Integer The total number of downloads for this video
Example
{
  "download_count": 485,
}

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).
end_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
sd_download_count Integer The total number of times your video was downloaded in SD resolution
hd_download_count Integer The total number of times your videos was downloaded in HD resolution
uhd_download_count Integer The total number of times your video was downloaded in UHD resolution
source_download_count Integer The total number of times your video was downloaded using the originally uploaded video
Example
[
  {
    "date": "2012-12-31",
    "sd_download_count": 7,
    "hd_download_count": 201,
    "udh_download_count": 7,
    "source_download_count": 157
  },
  {
    "date": "2013-01-01",
    "sd_download_count": 6,
    "hd_download_count": 204,
    "uhd_download_count": 6,
    "source_download_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 occurred
play_count Integer The total number of plays that occurred 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).
end_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 occurred
play_count Integer The total number of plays that occurred 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).
end_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 occurred 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).
end_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 occurred 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 occurred 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).
end_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 occurred 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
      },
      ...
    ]
  }
]

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 occurred 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

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).
end_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.
device_types Array An array of device types and the number of plays that occurred 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 occurred 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

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).
end_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.
device_types Array An array of device types and the number of plays that occurred 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"
      }
    ]
  },
  ...
]

Popular videos

Overall

URL Method
https://api.sproutvideo.com/v1/stats/popular_videos GET
Response
Name Type Description
video_id String The id of the video.
play_count Integer The total number of plays for that video.
Example
{
  "39ebe8581bc281016d": 29741,
  "1e0f9ca129195bd188": 5683,
  ...
}

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).
end_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.
popular_videos Object An object of video ids and the number of plays that videos received on that particular date.
Example
[
  {
    "date": "2019-06-12",
    "popular_videos": {
      "39ebe8581bc281016d": 41,
      "1e0f9ca129195bd188": 5,
    }
  },
  {
    "date": "2019-06-13",
    "popular_videos": {
      "39ebe8581bc281016d": 19,
      "1e0f9ca129195bd188": 12,
    }
  },
  ...
]

Popular downloads

Overall

URL Method
https://api.sproutvideo.com/v1/stats/popular_downloads GET
Response
Name Type Description
video_id String The id of the video.
download_count Integer The total number of downloads for that video.
Example
{
  "39ebe8581bc281016d": 29741,
  "1e0f9ca129195bd188": 5683,
  ...
}

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).
end_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.
popular_downloads Object An object of video ids and the number of downloads that videos received on that particular date.
Example
[
  {
    "date": "2019-06-12",
    "popular_downloads": {
      "39ebe8581bc281016d": 41,
      "1e0f9ca129195bd188": 5,
    }
  },
  {
    "date": "2019-06-13",
    "popular_downloads": {
      "39ebe8581bc281016d": 19,
      "1e0f9ca129195bd188": 12,
    }
  },
  ...
]

Live Analytics

Live 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/live_streams/counts GET
Response
Name Type Description
play_count Integer The total number of plays across all of your live streams
impression_count Integer The total number of times your live streams have been displayed on a webpage
unique_play_count Integer The total number of unique individuals who have played your live streams
unique_impression_count Integer The total number of unique individuals who have seen your live streams on a webpage
Example
{
  "play_count": 16189,
  "impression_count": 201216,
  "unique_play_count": 8146,
  "unique_impression_count": 65950
}

Per Live Stream

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

Domains

Per Live Stream

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

Geo

Per Live Stream

URL Method
https://api.sproutvideo.com/v1/stats/live_streams/:live_stream_id/geo 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 occurred 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"
  },
  ...
]

Device Types

Per Live Stream

URL Method
https://api.sproutvideo.com/v1/stats/live_streams/:live_stream_id/device_types GET
Response
Name Type Description
device_type String The type of device used to play this live stream.
play_count Integer The total number of plays that occurred 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"
  },
  ...
]

Live Stream Overview

Overall

URL Method
https://api.sproutvideo.com/v1/stats/live_streams/:live_stream_id/overview GET
Response
Name Type Description
peak_viewers Integer The highest number of concurrent viewers that watched this live stream.
total_viewers Integer The total number of times this live stream was watched.
unique_viewers Integer The total number unique of viewers that have watched this live stream.
avg_time_watched Integer The average amount of time viewers spent watching your live stream in seconds.
viewers_by_time Array An array of concurrent viewers for every ten second period of your live stream.
Example
{
  "peak_viewers": 81,
  "total_viewers": 149,
  "unique_viewers": 125,
  "avg_time_watched": 1194.72,
  "viewers_by_time": [
    [
      1593536760,
      65
    ],
    [
      1593536770,
      67
    ],
    [
      1593536780,
      68
    ]
    ...
  ]
}

API Clients