Queries look like normal calls to your assets collection with additional query string parameters. The following parameters are supported:

where: filter assets with a subset of SQL

orderby: order the results of your query (defaults to creation time, descending)

limit: number of assets returned on a result page
			

All query string values must be URI-encoded. For readability, the documentation uses the actual characters rather than the URI-encoded versions.

All strings must be enclosed in single-quotes: 'value', not "value". This will appear escaped as %27value%27.

If the string contains an apostrophe, it must be escaped with a backslash. This will appear escaped as %5C%27 (for example name='Bob\'s' will be escaped as name=%27Bob%5C%27s%27)

The where query consists of one or more clauses joined by an AND or OR conjunction.

Common words such as "a" and "the" are excluded from the search.

Deleted assets will never be included in query results.

Properties with null values cannot be searched for.

Searches are case-insensitive and fuzzy match different forms of a word (e.g. plurals). For example, querying for

description = 'Cat videos'

Will return assets with the following descriptions:

"Videos about cats"

"Funny video of a cat"

"Cats watching videos"

Comparison

All comparison functions are supported for integer and string fields on assets. (<, <=, =, >=, >, !=)

name = 'Spiderman'

duration < 600

Metadata

Custom metadata can be queried using the following syntax:

metadata.key = value

The metadata key can be digits and word characters (a to z, A to Z, 0 to 9). In addition, the key can be one of the following special characters: - _ ! @ # $ % & ^ * ( ) . ?

Note: the following characters must be escaped. Please use HTML escape codes given in the table below:

!	%21
#	%23
$	%24
^	%5E

Queries can be combined with a query string parameter of "include=metadata" to include the metadata in the asset response hash.

/v2/assets?where=metadata.genre='Comedy'&include=metadata

Labels

Labels can be queried using the following syntax:

labels INCLUDES 'Sports'

The results do not include assets assigned to sub-labels. For example, 'Baseball' is a sublabel of 'Sports'. Querying for the assets assigned to 'Sports' will not return assets assigned to 'Baseball'.

Queries for label intersection are supported:

/v2/assets?where=labels INCLUDES 'Sports' AND labels INCLUDES 'Baseball'

This query will return assets assigned to both 'Sports' and 'Baseball'. We recommend you use no more than three labels INCLUDES in an API call.

Flight Times

Assets can be filtered based on start and end dates. For example, these restrictions limit the results to assets that are playable on February 20:

time_restrictions.start_date <= '2011-02-20T00:00:00Z' and
time_restrictions.end_date >= '2011-02-21T00:00:00Z'

NULL end dates are treated as positive-infinity (the asset will continue to play forever). Thus, if your query specifies "end_date > (somedate)" all assets with no end date will also be returned.

If an asset uses recurring flight times, the start and end dates will reflect the start and end dates of the full recurrence, and not individual recurrence windows.

Note that querying for flight times will not take publishing rules into account. The query will only look at the flight time restrictions of the asset itself.

Assets in query results can be ordered by name, duration, asset_type, or creation time (created_at). This can be in ASCENDING or DESCENDING order. The default ordering is created_at, in DESCENDING order (most recent first).

Queries can not be ordered by metadata or labels.

orderby=name DESCENDING
orderby=name ASCENDING

Queries can contain * wildcards as the value of the 'where' query string parameter or within the search term.

Using the * wildcard as the value of the 'where' query string parameter will search for an asset by title, metadata, and description but NOT by labels. For example, the following query returns all assets that contain an exact match of the word 'data' in their metadata, title, or description but NOT in its labels.

where=*='data'

Using the * wildcard within the search term allows for partial word searching. Note that partial words must be at least 3 characters long. For example, the following query returns all assets that contain a partial word of 'data' in their description.

where=description='*data*'

Examples

The first 5 movies where the description is "Under the sea." that are greater than ten minutes long. The videos are ordered by created_at in ascending order.

SELECT * WHERE description = 'Under the sea.' AND duration > 600 ORDER BY created_at descending

/v2/assets?where=description='Under the sea.' AND duration > 600&orderby=created_at descending&limit=5

Get assets given a list of embed codes

SELECT * WHERE embed_code IN ('g0YzBnMjoGiHUtGoWW4pFzzhTZpKLZUi',
                              'g1YzBnMjrEWdqX0gNdtKwTwQREhEkf9e')

/v2/assets?where=embed_code IN ('g0YzBnMjoGiHUtGoWW4pFzzhTZpKLZUi','g1YzBnMjrEWdqX0gNdtKwTwQREhEkf9e')

All assets with the genre "Instructional" using custom metadata.

SELECT * WHERE metadata.key='genre' AND metadata.value='Instructional'

/v2/assets?where=metadata.genre = 'Instructional'

All assets tagged with the label "Case Study"

SELECT * WHERE labels INCLUDES 'Case Study'

/v2/assets?where=labels INCLUDES 'Case Study'

All assets modified after a certain date/time

SELECT * WHERE updated_at > '2011-06-04T01:22:50Z'

/v2/assets?where=updated_at>'2011-06-04T01:22:50Z'

This example returns the first two assets that have "cat" and "funny" in the description, and are more than 10 minutes long:

[GET]/v2/assets?where=description='cat funny'+AND+duration>600&orderby=name&limit=2

Backlot API returns a response similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":19000,
         "name":"Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-25T15:32:57+00:00",
         "embed_code":"IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt",
         "time_restrictions":null,
         "updated_at":"2011-08-29T23:12:09+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-25 at 08.31.mov",
         "description":"A video of funny cats.",
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":25959,
         "name":"More Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/9hcDdkMjq4LUKvPP-vJcgDds_TPIsP0u/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-05T21:49:46+00:00",
         "embed_code":"9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte",
         "time_restrictions":null,
         "updated_at":"2011-06-01T23:13:40+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-05 at 14.44.mov",
         "description":"Can there really be more funny cat videos? Yes.",
         "status":"live"
      }
   ],
   "next_page":"/v2/assets?limit=2&page_token=1314306109%3B1saGRyMjoOgjkUSjod_1TQINs_HOQnoU"
}

This example gets a list of assets that match the specified embed codes:

[GET]/v2/assets?where=embed_code+IN+('IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt','9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte')

Backlot API returns a response similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":19000,
         "name":"Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-25T15:32:57+00:00",
         "embed_code":"IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt",
         "time_restrictions":null,
         "updated_at":"2011-08-29T23:12:09+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-25 at 08.31.mov",
         "description":"A video of funny cats.",
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":25959,
         "name":"More Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/9hcDdkMjq4LUKvPP-vJcgDds_TPIsP0u/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-05T21:49:46+00:00",
         "embed_code":"9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte",
         "time_restrictions":null,
         "updated_at":"2011-06-01T23:13:40+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-05 at 14.44.mov",
         "description":"Can there really be more funny cat videos? Yes.",
         "status":"live"
      }
   ]
}

This example gets a list of assets that have a value of the category metadata key equal to "Cat Videos":

[GET]/v2/assets?where=metadata.category='Cat Videos'&include=metadata

Backlot API generates a feed similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":19000,
         "name":"Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-25T15:32:57+00:00",
         "embed_code":"IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt",
         "time_restrictions":null,
         "updated_at":"2011-08-29T23:12:09+00:00",
         "external_id":null,
         "metadata":{  
            "category":"Cat Videos"            "rating":"G"
         },
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-25 at 08.31.mov",
         "description":"A video of funny cats.",
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":25959,
         "name":"More Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/9hcDdkMjq4LUKvPP-vJcgDds_TPIsP0u/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-05T21:49:46+00:00",
         "embed_code":"9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte",
         "time_restrictions":null,
         "updated_at":"2011-06-01T23:13:40+00:00",
         "external_id":null,
         "metadata":{  
            "category":"Cat Videos"            "rating":"PG"
         },
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-05 at 14.44.mov",
         "description":"Can there really be more funny cat videos? Yes.",
         "status":"live"
      }
   ]
}

This example returns all videos with the "funny" label:

[GET]/v2/assets?where=labels+INCLUDES+'funny'

Backlot API returns a response similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":19000,
         "name":"Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-25T15:32:57+00:00",
         "embed_code":"IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt",
         "time_restrictions":null,
         "updated_at":"2011-08-29T23:12:09+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-25 at 08.31.mov",
         "description":"A video of funny cats.",
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":25959,
         "name":"More Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/9hcDdkMjq4LUKvPP-vJcgDds_TPIsP0u/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-05T21:49:46+00:00",
         "embed_code":"9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte",
         "time_restrictions":null,
         "updated_at":"2011-06-01T23:13:40+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-05 at 14.44.mov",
         "description":"Can there really be more funny cat videos? Yes.",
         "status":"live"
      }
   ]
}

Flight times restrict when content can be played. This example returns assets that were playable for the entirety of June 2011:

[GET]/v2/assets?where=time_restrictions.start_date<='2011-06-01T00:00:00Z'+AND+time_restrictions.end_date>='2011-07-01T00:00:00Z'

Backlot API returns a response similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":3366,
         "name":"My movie",
         "preview_image_url":"http://ak.c.ooyala.com/B5bzAzMzrrnbUrxt_vBj0hLcjgdQSkSH/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-01-21T23:37:28+00:00",
         "embed_code":"B5bzAzMzrrnbUrxt_vBj0hLcjgdQSkSH",
         "time_restrictions":{  
            "type":"range",
            "start_date":"2011-06-01T00:00:00Z",
            "end_date":"2011-06-15T00:00:00Z"
         }         "updated_at":"2011-11-29T00:40:37+00:00",
         "external_id":null,
         "original_file_name":"My movie.mov",
         "hosted_at":null,
         "description":null,
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":0,
         "name":"My other movie",
         "preview_image_url":null,
         "created_at":"2011-01-01T19:40:32+00:00",
         "embed_code":"QycmV4Mjp_iICcP6fhpiHsY81jDgmOUY",
         "time_restrictions":{  
            "type":"range",
            "start_date":"2011-06-015T00:00:00Z",
            "end_date":null
         }         "updated_at":"2011-10-26T19:40:32+00:00",
         "external_id":null,
         "original_file_name":"My other movie.avi",
         "hosted_at":null,
         "description":null,
         "status":"uploading"
      }
   ]
}