Get filtered query results with the Wowza Video REST API

Learn how to use the filter parameter to get filtered results from REST API queries made in the Wowza Video™ service. The filter parameter restricts the data that gets returned to one or more values associated with a field.

About filters

To use the filter query parameter, you'll send a GETrequest to an endpoint that supports filtering and append a query URL with a two-part expression that specifies the field on which to filter and the logic (comparison operator) to use to filter. You can use as many filters as you want, combining them with an ampersand (&). Order doesn't matter; multiple filters are additive.

Use the syntax ?filter[n][field]=value&filter[n][comparison operator]=*value where n is a zero-based index. For example, to return all transcoders that aren't actively running (all transcoders whose state isn't started):

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/transcoders?filter[0][field]=state&filter[0][in]=starting,resetting,stopping,stopped"

Filtering by date and time

Queries for created_at or updated_at need to be made in Coordinated Universal Time (UTC) format. There are online converters available to help you convert your local time to UTC. Your dates should be formatted as follows: YYYY-MM-DDT HH:MM:SSZ using 24-hour clock (military) time and including the T and Z.

Examples of UTC:

• May 25, 2022 at 1:07:49 PM = 2022-05-25T13:07:49.000Z
• March 14, 2015 at 8:25:20 PM = 2015-03-14T20:25:20.000Z
• August 29, 2019 at at 3:47 AM = 2019-08-29T03:47:53.000Z

Supported filters

The following filters are supported.

Endpoints and fields that support filters

The following endpoints support the filter parameter in the GET request:

• /assets

  Info

  The /assets endpoint has additional functionality for using ?query expressions. See the Query parameter for assets endpoint section below to learn more.

• /live_streams
• /real_time
• /recordings
• /schedules
• /stream_sources
• /stream_targets
• /transcoders
• /vod_streams

For the endpoints listed above, you can filter on the following fields, where they exist:

• id
• name
• state
• created_at
• updated_at
• playback_enabled (vod streams only)

Sample requests

Below are some sample filter requests to get you started.

Transcoders

Return only transcoders whose state is stopped:

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/transcoders?filter[0][field]=state&filter[0][eq]=stopped"

Return only transcoders that are started and have the name MyTranscoder or MyOtherTranscoder:

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/transcoders?filter[0][field]=state&filter[0][eq]=started&filter[1][field]=name&filter[1][in]=MyTranscoder,MyOtherTranscoder"

Live streams

Return live streams created after March 14, 2022 at midnight UTC.

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" 
"${WV_HOST}/api/${WV_VERSION}/live_streams?filter[0][field]=created_at&filter[0][gte]=2022-03-14T00:00:00.000Z"

Return live streams with specified id. You can enter as many ids as you'd like to filter by separated by commas.

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/live_streams?filter[0][field]=id&filter[0][in]=DF2GmmPH,c5FNnMp0"

Recordings

Return all recordings whose state is not completed.

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/recordings?filter[0][field]=state&filter[1][nin]=completed"

Schedules

Return all schedules with a created_at date older than January 1, 2021 sorted in descending order.

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
{WV_HOST}/api/${WV_VERSION}/schedules?filter[0][field]=created_at&filter[0][lte]=2021-01-01T00:00:00Z&filter[1][field]=created_at&filter[1][sort]=desc"

VOD streams

Return VOD streams that have the state of playback_enabled set to false.

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \
"${WV_HOST}/api/${WV_VERSION}/vod_streams?filter[0][field]=playback_enabled&filter[0][eq]=false"

Query parameter for assets endpoint

Prior to version 1.10 of the REST API, the /assets endpoint only supported query expressions as a way of filtering results. With version 1.10 and later, the /assets endpoint supports both the filter parameter like our other endpoints do, described above, as well as the query parameter.

You can build a ?query expression with the following syntax ?query=[x] with optional additional parameters as shown below. Partial queries are allowed.

When you execute a ?query expression, the following fields are searched:

• title
• tag_list

The following parameters are also valid, but optional:

• sort_column : defaults to created_at
• sort_direction : desc (default) or asc
• page : defaults to 1
• per_page : defaults to 15
• state : completed, failed, no_video, processing, queued, uploading

Sample requests

Return all failed assets.

    curl -X GET -g \
    -H "Authorization: Bearer ${WV_JWT}" \
    "${WV_HOST}/api/${WV_VERSION}/assets?state=failed

All completed assets including the title "sample" with 30 results per page.

    curl -X GET -g \
    -H "Authorization: Bearer ${WV_JWT}" \
    "${WV_HOST}/api/${WV_VERSION}/assets?sort_direction=desc&sort_column=created_at&per_page=30&page=1&state=completed&query=sample

All assets with the tag "promotion".

    curl -X GET -g \
    -H "Authorization: Bearer ${WV_JWT}" \
    "${WV_HOST}/api/${WV_VERSION}/assets?query=promotion