CMS API: Video Search v2

Introduction

Version 2 of the video search used by the CMS API is the recommended syntax for new integrations. It supports the features that most v1 searches rely on, including date ranges (both the .. and [a TO b] forms), NOW, relative offsets, comma-separated values, and reference ID prefix matching. If you have an existing q integration, see Preparing to migrate. To see Version 1, go to CMS/Playback API: Videos Search v1.

Choosing which syntax to use is a simple matter of choosing the appropriate URL parameter:

• To use the new v2 search:

      .../videos?query={search_string}

• To use the original search:

      .../videos?q={search_string}

Basics

The basic element of a search string is a search term, which may be prefixed by a field name. If the field name is included, only that metadata field will be searched. Otherwise, several fields (listed below) will be searched.

For example:

When you provide no field name to search, the request searches for that value in these eight fields:

• id
• name
• description
• long_description
• tags
• reference_id
• custom_fields (all custom fields together)
• variants

The supported fields to search are:

In both the examples shown above, videos that do not have the word "bird" in any relevant field might still be returned. The next section explains how to limit search results to only videos that have the specified terms.

Ignored words

Certain words are ignored in search strings because they are so common that they are likely to return many results unrelated to what you are actually searching for. Below is a list of words that are ignored by search:

"a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"

In addition, non-alphanumeric characters such as hyphens, underscores, line-breaks, "$", "&", "*", etc. are treated as word delimiters. For example, a search string like small-town will be treated as small town.

What is stemming?

Video fields that support stemming return words that have the stem of the search word in common. In addition, stemming supports entering whole words only, not partial words:

• Example 1: Searching on running will return results containing: running, run, runs
• Example 2: Searching on vid will not return results containing: video

Search with stemming works in the following fields:

• custom_fields
• description
• name
• long_description
• tags
• labels

Advanced search

There are some modifiers that help you limit search results to exactly the videos you want.

Phrase search

You can search for a phrase (rather than a single word) by placing in quotation marks:

• "blue heron"
• name:"blue heron"

Quoting values

Quotation marks are not only for phrases. Put double quotes around any field value that contains anything other than letters, digits, underscores, and periods. In particular, quote a value that contains a space or any of these characters:

:   /   |   =   $   %   &   !   *

The list is illustrative rather than exhaustive. The rule above is the reliable one: if the value is not made up only of letters, digits, underscores, and periods, quote it. An apostrophe, for example, is not in the list but is covered by the rule.

Leaving the quotes off has one of two outcomes, depending on the character.

Some characters split the value

A space, or one of / | = $, splits the value. The first piece stays attached to the field you named, and every remaining piece becomes a free text search across the eight default fields. This returns no error, so an incorrect result can go unnoticed.

tags:women's health asks for the tag women's plus the free text health, and can return far more videos than intended. tags:"women's health" asks for the one tag. In the other direction, tags:$gaeilge searches for a different tag (gaeilge) than the one you asked for.

Some characters make the query unreadable

A : or a * inside a value cannot be interpreted at all, so the whole request is rejected with HTTP 400 and a message naming the character and its position. tags:modelid:414 is refused, while tags:"modelid:414" returns the videos you asked for. See When a query cannot be parsed.

The remaining characters in the list above, % & !, should be quoted for the same reason even though the exact outcome varies. Quoting is the one action that is correct in every case.

Wildcards are not supported

The asterisk is not a wildcard in a text value. Outside a date or numeric range, where * means an open bound, an asterisk in a value cannot be interpreted, so tags:spring* is rejected with HTTP 400 (unexpected input '*' at position 11) rather than matching every tag starting with "spring".

What to do depends on what you meant by it:

• If the asterisk is literally part of the value you are looking for, quote it so the query stays valid: tags:"spring*". Punctuation is treated as a word delimiter in the text being matched (see Ignored words), so the asterisk will not narrow the match by itself.
• If you meant it as a wildcard, remove it. To match the beginning of a value, use reference_id, which prefix-matches by design (see below). No other field supports prefix matching.

Tag lists

A comma-separated list of tags matches videos that have any of the values:

    tags:sea,mammal

returns videos tagged sea or mammal.

See Quoting values for which characters need the quotes.

Custom field lists

Custom field values may also be comma-separated, with the same "any of these" meaning:

    +product_number:H517497,H517498

matches videos whose product_number is either value.

Searching by reference ID

reference_id does not behave like the other string fields. An unquoted value matches reference IDs that equal or begin with that value, with exact matches ranked first. Matching is case-insensitive.

Do not append an asterisk to get a prefix search. reference_id:abc already does it, and reference_id:abc* is not supported.

Playable videos

There are two ways to limit results to videos that a viewer could play right now.

The playable_only parameter

    .../videos?query=name:bird&playable_only=true

The playable search term

    .../videos?query=%2Bplayable:true%20name:bird

Both apply the same definition. A video is playable when all four of these hold:

• complete is true, meaning at least one rendition exists
• state is ACTIVE (so INACTIVE, PENDING and DELETED videos are excluded)
• schedule.starts_at is in the past, or is not set
• schedule.ends_at is in the future, or is not set

A video with no schedule at all counts as playable, provided the other conditions hold.

Date/Times and Ranges

You can express a date range in either of two forms:

• Bracket syntax: updated_at:[2020-01-01T00:00:00.000Z TO 2020-12-31T00:00:00.000Z]
• Shorthand syntax: updated_at:2020-01-01..2020-12-31

Both bounds are inclusive. Both forms accept dates, date-times and NOW. Relative offsets are the one value type the two forms do not treat alike, so they have their own section below.

Milliseconds and time zones

Milliseconds are optional. When you include them, three digits is the usual form (2019-09-30T14:24:33.512Z); six digits are also accepted.

The two syntaxes differ in one respect, the time zone designator:

• In the bracket syntax the Z suffix is required, so times are always UTC.
• In the shorthand syntax a date-time may carry either Z or a numeric UTC offset: updated_at:2026-08-07T14:30:47-07:00..NOW. The offset must be the full ±HH:MM form. ±HH and ±HHMM are not accepted.

Dates without a time

A bare yyyy-MM-dd used as the lower bound means the start of that day. Used as the upper bound, it covers the whole of that day, in both syntaxes. So both of these match everything created on 31 December:

created_at:2020-12-31..2020-12-31
created_at:[2020-12-31 TO 2020-12-31]

Open ended ranges

In the shorthand syntax, leave off either end:

• created_at:2020-01-01.. from a date onward
• created_at:..2020-01-01 up to a date

In the bracket syntax, use * for the open end: created_at:[2020-01-01 TO *].

Relative offsets

A relative offset is a sign, a number, and a unit, measured from the current time: updated_at:-7days..NOW.

The units are YEAR(S), MONTH(S), DAY(S) or D, HOUR(S) or H, and MINUTE(S). Case does not matter, with one exception: in the shorthand syntax the bare letter M is rejected as ambiguous, while a bare lowercase m means minutes. The bracket syntax does not reject it: there M means months. Spell out MINUTE(S) or MONTH(S) rather than relying on a single letter for either.

Below are some sample date/time search strings.

Searching for clips by source video

The clip_source_video_id field identifies the original source video from which a clip was created.

When a clip is generated from a live job (for example, via the Brightcove Studio Live module), the resulting clip includes a metadata property called clip_source_video_id. This property stores the video ID of the original live job that the clip was derived from.

This field can be used in CMS API search queries to retrieve all clips created from a specific live video. For instance, when viewing a live job in Brightcove Studio and opening the Saved Clips list, the Studio interface calls the Get Videos API with a query that filters by clip_source_video_id, returning all clips associated with that live job.

Example Query

GET https://cms.api.brightcove.com/v1/accounts/{account_id}/counts/videos?query=+clip_source_video_id:{source_video_id}

Use Cases

• Retrieve all clips generated from a particular live job or source video.
• Organise and manage clips programmatically using the CMS API.

When a query cannot be parsed

If the search string does not follow the syntax on this page, the request is rejected with HTTP 400, and the response body carries a message that says what could not be read and where:

unexpected input ':' at position 12

If you need to recognize these rejections in code, match on the message text: the JSON structure around it is not part of the search contract and may change. The count endpoints reject the same search strings in the same way.

Reading the message

• The position is zero-based, counted in characters from the start of the decoded search string. In tags:modelid:414, position 12 is the second colon.
• Two message forms cover most cases: unexpected input '<text>' at position <n> when something appears where it cannot, and unexpected end of input at position <n> when the string stops early, for example with an unclosed parenthesis.
• A few checks produce their own message instead. The clearest example is the ambiguous relative-time unit described under Relative offsets.

Known issues

• Always send a sort parameter when paging. If you do not, results are ordered by relevance, and relevance order is not stable enough to page through: the same video can appear on two pages, or on none. This is the cause of the duplicate results that are sometimes reported.

  Any sort field gives you a stable order. Note that sorting on updated_at means a video that changes while you are paging can move behind a page you already fetched, so an integration that cannot tolerate missed videos should sort on created_at.

• A search response does not carry a total. When you need to know how many videos match a query, send the same query to the count endpoint (/counts/videos), which returns an exact count. Do not try to derive a total from a page of search results.

For general search instructions in Video Cloud, see Media Module Search.