# 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}" \
"${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.

Info
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`
The /assets endpoint has additional functionality for
using `?query` expressions. See the [Query parameter for assets endpoint section](#query-parameter-for-assets-endpoint) 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.

Info
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}" \
    "${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
```