API reference

Base URL

Account path

In all cases, requests will be made for a specific Video Cloud Account. You will always need to add the term “accounts” followed by your account ID to the base URL:

https://audience.api.brightcove.com/v1/accounts/{account_id}

Authentication

The Audience API uses the Brightcove OAuth Service to authenticate calls.

You will first need to obtain client credentials (a client_id and client_secret). This is a one-time operation that can be performed using the OAuth Credentials UI. You will need permissions for Audience/Read operations:

Required Permissions

You can get client credentials directly from the Brightcove OAuth Service using cURL or Postman.

You will also need an access_token, which is obtained using the client_id and client_secret and passed in an Authorization header with your API request:

Authorization: Bearer {access_token}

The access_token expires after five minutes, so you must obtain one for each request, or check to make sure that your token is still valid. See Getting Access Tokens for a detailed explanation of how to get access tokens, including code samples.

Error handling

If an error occurs, the API will respond with one of the following status codes and a corresponding error code in the response body:

Parameters

There are several parameters you can add to requests to limit and filter the data retrieved. These apply to all the request types described in the sections that follow.

Filtering results

You can filter the results using the where parameter. The syntax for filters is:

where=field1==value1;field2==value2

For example:

where=video_id==123456789;video_name==test

Commas are treated as logical ORs and semicolons as logical ANDs. For example, where=video_id==1234,5678;video_name=test is interpreted as "where video_id = 1234 OR 5678, AND video_name = test".

Selecting fields to return

A list of fields may be specified in the request to limit the results to that subset of fields. The syntax for fields is:

fields=field1,field4

For example:

fields=video_id,video_name

The fields that you can filter and sort on are detailed for each request type in the sections that follow.

Date ranges

Date ranges can be specified in from and to parameters and are applied to the date that the view event was last updated (the updated_at field). Date ranges can be indicated in the following formats:

The text value now which represents the current time

Epoch time values in milliseconds, such as 1377047323000

Dates expressed in ISO 8601 standard international date format: YYYY-MM-DD format, such as 2013-09-12. For dates expressed in this format:

Any date range specified will be interpreted in UTC

The time for the date give will be interpreted as midnight ( 00:00:00) on the date specified

Relative dates: you can express either of the to and from values relative to the other one in d (days), h (hours), m (minutes), or s (sec). For example:

from=2015-01-01&to=31d

from=-48h&to=now

from=-2d&to=now (will give the same results as the previous example)

from=-365d&to=2015-12-31

from=-10m&to=now

Paging results

The limit is the number of items to return (default: 25; maximum: 100). offset is the number of items to skip (default: 0). You can use limit and offset together to create an app that pages through the results. Each includes the limit, offset, and count., which you can use to set up iteration over total results. For example, in JavaScript, you could get the total iterations required like this:

// response is the JSON-parsed response from the first request
var totalRequests = Math.ceil(response.count / response.limit)

Retrieving view events

To retrieve view events in an account, perform a GET request to the view_events resource: