Product Updates | Contact Support | System Status
Page Contents

    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

    Page last updated on 03 Jan 2022