Searching for Channels using the Channels API

This topic explains how to search for Cloud Playout channels using the Channels API.

Introduction

If you create many Cloud Playout channels, you will likely find it useful to search for the one(s) you want to work on at the moment. Cloud Playout provides a robust mechanism for searching for channels using either the Studio module or the Channels API.

This topic covers searching for channels using the Channels API.

Search Parameter

Channel search uses a parameter (q) that is added to the GET CHANNELS request:

https://cm.cloudplayout.brightcove.com/accounts/{account_id}/cp_channels

The general form of the q parameter with a value is:

q=search_text advanced_search

The components of the search query are as follows:

  • search_text - the word(s) to search for in name, description, or id of the channel
  • advanced_search - a set of filters that narrow the search

Both the search_text and advanced_search filters are optional.

Example

...?q=nature stories loop:true desc:"nature stories" startTime:2021-12-11 10:30:00..2021-12-12 12:23:00

Advanced search patterns

The advanced_search part of the query is a combination of patterns separated by a space. Patterns that don't match the accepted ones will result in a error returned. The table below shows the supported patterns.

Advanced Search Patterns
Pattern Name Description Accepted Values
state to filter channels based on its state. This pattern accepts multiple values & the values should always be enclosed between square brackets - [] - even for a single value. This is a OR case. The API will fetch channels matching any of the given states. state:[draft,running,create_error] or
state:[running,stopping] or
state:[starting]
region to filter channels based on its region. This pattern accepts multiple values & the values should always be enclosed between square brackets - [] - even for a single value. This is a OR case. The API will fetch channels matching any of the given regions. region:[us-east-1,us-east-2,us-west-2] or
region:[eu-west-1,eu-west-2] or
region:[us-west-2]
live to filter channels with live input live:true/false
loop to filter looped/non-looped channels. loop:true/false
dynamicOverlays to filter channels with dynamic overlays dynamicOverlays:true/false
output to filter based on channel outputs. Accepts multiple values and the values should always be enclosed between square brackets - [] - even for a single value. Though only accepted values are rtmp, rtp & s3. This is a AND case. If rtmp & s3 are chosen then the API will filter channels with both rtmp & s3 as outputs. output:[rtmp,s3] or
output:[rtp,s3] or
output:[rtmp]
name to filter based on a term contained in the channel name. When the name contains spaces then it should be wrapped inside single/double quotes. name:nature or
name:'nature stories' or
name:"nature videos"
desc to filter based on a term contained in the channel description. When the value contains spaces then it should be wrapped inside single/double quotes. desc:nature or
desc:'nature stories' or
desc:"nature videos 'amateur'"
id to filter based on channel public id id:67ytd89 or id:252748cef5de464e8e8f87b7e15e7d34
startTime to filter based on channel start time range. Both from and to date times are separated by .. and the accepted date time format is yyyy-mm-dd hh:mm:ss. A timezone offset is also accepted and is optional. When not provided the value will be considered as UTC date time. Only 24hr format is accepted. startTime:2021-10-29 05:57:10..2021-10-30 05:57:10 or
startTime:..2021-10-30 05:57:10 or
startTime:2021-10-30 05:57:10.. or
startTime:2021-10-29 05:57:10 +09:30..2021-10-30 05:57:10 +09:30
createTime to filter based on channel creation time range. Both from and to date times are separated by .. and the accepted date time format is yyyy-mm-dd hh:mm:ss. A timezone offset is also accepted and is optional. When not provided the value will be considered as UTC date time. Only 24hr format is accepted. createTime:2021-10-29 05:57:10..2021-10-30 05:57:10 or
createTime:..2021-10-30 05:57:10 or
createTime:2021-10-30 05:57:10.. or
createTime:2021-10-29 05:57:10 +09:30..2021-10-30 05:57:10 +09:30

Examples

Below is a sample query:

...?q=hello world 'in this world' loop:true live:true startTime:..2021-12-11 10:30:00 state:[draft,running] output:[rtmp,s3]

Here the search_text will be hello world 'in this world' And advanced_search will be loop:true live:true startTime:..2021-12-11 10:30:00 state:[draft,running] output:[rtmp,s3]

Some more examples:

Search Examples
search_text advanced_search comments
hello "world is (empty) Only the search_text will be searched against id, name, and description
(empty) loop:true name:cloud Only channels matching the filters will be returned
ced52df ad:true region[us-east-1,us-west-2] Results will include channels where "ced52df" is contained in the id, name, or description AND the channels match the filters