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.

Note: The /assets endpoint uses a different query filter. See the Filtering assets section.

About filters


To use the filter query parameter, you'll send a GET request 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-DD-MMT HH:MM:SSZ using 24-hour clock ("military") time and including the T and Z.

Note: In UTC the T marks the end of the date portion and the Z represents zero UTC time offset. 

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.

FilterDescription
eq==
neq!=
gt>
gte>=
lt<
lte<=
inOne in the set equals the value. Takes a comma-separated string of values.
ninNone in the set equal the value. Takes a comma-separated string of values.
likeContains the value.
You can use * or % as a wildcard.
sortIn ascending (asc) or descending (desc) order.
Example: filter[0][sort] = desc

Endpoints and fields that support filters


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

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

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 ids. 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"


Filtering assets

The /assets endpoint uses a different type of filtering query. You will build a ?query expression with the following syntax ?query=[x]with optional additional parameters as shown below. Partial queries are allowed.

Note: When filtering by tag, only tags that are applied to active assets are queried. Tags which only exist on deleted assets will not be returned.

The following fields can be queried:

  • 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