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 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}" \

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.

Filter Description
eq ==
neq !=
gt >
gte >=
lt <
lte <=
in One in the set equals the value. Takes a comma-separated string of values.
nin None in the set equal the value. Takes a comma-separated string of values.
like Contains the value.
You can use * or % as a wildcard.
sort In 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:

  • /assets
    Note: The /assets endpoint has additional functionality for using ?query expressions.
    See the Query parameter for /assets endpoint 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.


Return only transcoders whose state is stopped:

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \

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

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \

Live streams

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

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" 

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}" \


Return all recordings whose state is not completed.

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \


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}" \

VOD streams

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

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \

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.

Note: Only tags that are applied to active assets are queried. Tags which only exist on deleted assets will not be returned.

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}" \

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

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \

All assets with the tag "promotion".

curl -X GET -g \
-H "Authorization: Bearer ${WV_JWT}" \