Image & Video APIs
Menu

Search API method

Last updated: Apr-02-2025

The Admin API search method allows you fine control on filtering and retrieving information on all the assets in your product environment with the help of query expressions in a Lucene-like query language. You may want to use the search API method to:

  • Search by descriptive attributes such as public ID, filename, folders, tags, context, etc.
  • Search by file details such as type, format, file size, dimensions, etc.
  • Search by embedded data such as Exif, XMP, etc.
  • Search by analyzed data such as the number of faces, predominant colors, auto-tags, etc.
  • Request aggregate counts on specified asset attributes, for example the number of assets found per file format, delivery type, or asset type, or aggregate counts for custom-defined ranges on number bytes, image or video pixels, or video duration.

Tip
You can similarly use the search_folders API to search for folders that meet the criteria of a search expression.

On this page:

Quick example

Find images tagged with 'shirt', that were uploaded within the last day, and are larger than 1 MB in size. In the response, sort the results by public_id in descending order, and limit the returned results to 30 assets:

Search API tiers

The Search API has 2 tiers:

  • Tier 1: Includes support for using the search method with a large selection of fields, operators, and search syntax.

  • Tier 2 (Premium): Includes extra search functionality including support for search expressions based on image analysis and embedded metadata fields as well as support for aggregated counting information in the response. Functionality that's limited to Tier 2 is noted as such.

Tier activation and pricing

  • Tier 1 Search API functionality is automatically enabled for all product environments with up to 10 million assets. If your product environment has, or is approaching, 10 million assets, contact support.

  • Tier 2 is available upon request for Advanced plans and higher. Advanced plans can use Tier 2 at an extra cost for Advanced plans. Customers on Enterprise plans can use Tier 2 functionality up to 10 million assets (and at an additional cost for more than 10M assets). Regardless of your account plan, you must contact support to request the Tier 2 option.

Search method

The Search for resources method of the Admin API enables you to find the specific assets in your product environment that meet your specified criteria. To execute a search, use the search method and provide it with some parameters to refine your search.

All the parameters of the search method are optional, but in most cases you'll want to add at least the expression parameter, which describes the criteria for filtering the assets by the values of specified fields (attributes) in a Lucene-like query language. For a list of all available asset fields for the search expression, see Supported expression fields below.

You can also combine a query string with Boolean operators to form a more complex query. To learn about building search queries, see the Search expressions guide.

For details on all the optional parameters of the search method, see the Search method under the resources endpoint in the Admin API reference.

Notes
  • If you don't include a search expression or any other parameters in the search method call, it returns the 50 most recently created assets in descending order of creation time.
  • The search method is part of the rate-limited Admin API, and shares the same usage limits. See the Admin API documentation for more information on authentication, pagination and error handling.

Search examples

  1. Find assets containing 'shoe' in any field (attribute), include only the context metadata and tags fields in the details of each resource, and limit the returned results to 10 resources:

  2. Find assets containing 'shirt' in any field but not 'blue' in the tags field, sort the results by public_id` in descending order, and calculate an aggregation count based on the values of the format field:

  3. Find assets containing 'clothing' in any field and have an aspect ratio less than one (portrait orientation), sort the results by public_id in descending order, and calculate an aggregation count (supported for Tier 2 only) based on custom-defined ranges for the bytes (with ranges) and format attributes. (See a sample response for this example request.)

  4. Find the next page of 500 results, using the 'next_cursor' from the previous call (b16b8bd80426df43a107f26b0348), of a search for images tagged with 'sale' and uploaded within the last day. Sort the results by public_id in descending order:

Tip
For more examples, see the expression examples documentation.

Search response

The response includes the total count of assets matching the search criteria, the time taken to process the request, any aggregation counts requested (Tier 2 only), and the details of each of the assets (resources) found.

Sample JSON Response:

Tip
The status field in the response tells you whether the asset is active and visible with working delivery URLs or not_found if it’s deleted but also backed up.

Supported expression fields

You can use the following fields to limit your asset search criteria. The operators that you can use with a field depend on the field's value type. For details, see Field types and supported operators.

You can use all fields for all resource types (image, video, raw) unless otherwise specified. Additionally, all string fields support both exact and tokenized search unless otherwise specified.

See also
For a detailed overview and a variety of expression examples, see the Search expressions guide.
Field Name Type Examples Details
Asset Management
access_mode String (fixed list) access_mode:authenticated The authentication level currently set for the resource.
Possible values: public, authenticated
Case-sensitive
asset_id String asset_id=abcd10ef1234ab1c678def9a0c123 The immutable ID of the asset. An asset's asset_id is returned when assets are uploaded as well as when they're retrieved, such as when using the resources method.

Not supported for product environments using the legacy fixed folder mode.
asset_folder String asset_folder=test/sample // exact folder, no subfolders
asset_folder:sample/* // prefix, all contents of 'sample' under root
asset_folder:"my folder with spaces" // folder name containing spaces		 You can search for an exact folder path, or you can search for a folder prefix, which returns all contents of the specified folder and all its subfolders.
Case-sensitive.

Not supported for product environments using the legacy fixed folder mode.
context String context.productType:shoe
context.productType=shoe
context."key with spaces":myValue
context:keyname //check for key existence 		You can search for a specific key-value pair, or for all resources with a particular key regardless of the value, or with a particular value regardless of the key.
- To search for the value of a key, specify the key value of the context using the dot (.) notation, and the value using a colon (:).
- To check for the existence of a key name, specify the keyname you are searching for after an equal sign (=).
- Key names are exact match only and are case-sensitive.
- Values can be tokenized or exact match.
- Exact match (=) searches are case-sensitive.
- Tokenized searches (:) are case insensitive.
created_at Date created_at:["2022-11-12T12:00:00Z" TO 1w]
created_at:[4w TO 1w]
created_at>10d
created_at<1w
created_at<=2023-01-01
created_at<1486929412		 Note: If you include the time, the entire date and time need to be enclosed in quotation marks.
last_updated Date last_updated.tags_updated_at:["2022-10-22T12:00:00Z" TO "2022-11-22T12:00:00Z"]
last_updated.context_updated_at>"2022-10-22T12:00:00Z"		 You can search within any of the last_updated fields: access_control_updated_at, context_updated_at, metadata_updated_at, public_id_updated_at, tags_updated_at, or updated_at.

Note: If you include the time, the entire date and time need to be enclosed in quotation marks.
display_name String display_name="small white dog"
display_name:"small white"
public_id:dog*		 The user-friendly display name of the asset.

Not supported for product environments using the legacy fixed folder mode.
folder String folder=test/sample // exact folder, no subfolders
folder:sample/* // prefix, all contents of 'sample' under root
folder:"my folder with spaces" // folder name containing spaces		 You can search for an exact folder path, or you can search for a folder prefix, which returns all contents of the specified folder and all its subfolders.
Case-sensitive.

Supported only for product environments using the legacy fixed folder mode.
metadata String metadata.quantity_id<10 //int
metadata.name_id:john //string
metadata.city_id=paris_id //enum
metadata.exp_date>2021-01-01 //date
metadata.color_id:red_id //set		 Specify the external_id of any structured metadata field using the dot (.) notation, where the external ID is compared with a specified value according to the field's defined type (use the datasource external_id instead of a value for enum and set types). See metadata fields for details.
moderation_kind String moderation_kind=perception_point The moderation applied to the asset.

For assets marked for multiple moderations:

- During moderation: The moderation currently being applied to the asset.

- If the asset was rejected: The moderation that rejected the asset.

- If the asset was approved: The last moderation that was applied.

Possible values: manual, perception_point, webpurify, aws_rek, duplicate, aws_rek_video, google_video_moderation
Case-sensitive.
moderation_status String moderation_status=approved The current moderation status.
Possible values: pending, approved, rejected
Case-sensitive.
public_id String public_id=test/sample/dog
public_id:test/sample/dog
public_id:test/sample/dog*		 The full public ID, including slashes when relevant. You can search for an exact public_id, or you can search for a public_id prefix using the * operator.
Case-sensitive
tags String tags:siamese //tokenized search
tags=siamese //exact search
-tags=siamese //doesn't have the tag
tags="siamese cats" //tag includes a space
-tags //has no tags at all		 Exact match (=) searches are case-sensitive.
Tokenized searches (:) are case insensitive.
type String (fixed list) type:private The asset type.
Possible values: upload, private, authenticated, fetch, facebook, twitter, etc.
Exact match only. Case-sensitive.
uploaded_at Date uploaded_at<1d // uploaded date is smaller than the date one day ago = longer than 1 day ago.
Media Properties
aspect_ratio Number or String aspect_ratio="16:9"
aspect_ratio<=1		 You can specify the aspect ratio as a decimal number (comparisons round all aspect ratios to 5 decimal places for purposes of the check), or a string in the format "Width:Height".
Exact match only. Case-sensitive.
bytes Number bytes:[1000 TO 5000000]1
bytes>100000		 The file's size. You can append a b for bytes (default), a kb for kilobytes, a mb for megabytes, and a gb for gigabytes.
duration Number or String duration:[30s TO 2m]1
duration>5
duration<30s
duration<3m		 The duration of the video. You can append an s for seconds (default) or an m for minutes.
Video resources only.
filename String filename="hound-dog"
filename:(dog cat)
filename:hound*		 Refers to the last element of the public ID without a format extension. You can search for an exact or tokenized filename, or you can search for a filename prefix using the * operator.
Exact match (=) searches are case-sensitive. Tokenized searches (:) are case insensitive.
format String format=(jpg OR mp4) Exact match only. Case-insensitive.
height Number height<=100 Not relevant for raw files.
pixels Number pixels>400000 Number of total pixels (width x height). You can append a p for pixels (default) or an m for megapixels.
Not relevant for raw files.
resource_type String (fixed list) resource_type:image
resource_type:video		 Possible values: image, video, raw
Exact match only. Case-sensitive.
width Number width>100
width=1028		 Not relevant for raw files.
System
backup_bytes Number backup_bytes>0 // all resources that are backed up. If the resource is backed up, indicates the space taken in the backup system by all backed up versions. You can append a b for bytes (default), a kb for kilobytes, or a mb for megabytes.
status String (fixed list) status=deleted
status=deleted OR active		 Possible values: active, deleted
Notes:
- Resource data is stored in the database with status deleted only if the resource has a backup.
- By default, when you conduct a search, the response includes only resources with active status. If you want the response to include resources with a deleted status, you must use this field to specify it.
Exact match only. Case-sensitive.
Asset analysis and embedded metadata
(Tier 2)
accessibility_analysis.colorblind_accessibility_score Number accessibility_analysis.colorblind_accessibility_score>0.8 A score between 0 and 1 indicating the level of accessibility of the image to color blind people. Available only for images for which accessibility_analysis was set to true during upload (in the upload request or upload preset).

Note: The accessibility_analysis.colorblind_accessibility_score field is returned in searches including a with_field parameter specifying accessibility_analysis.
colors String colors:blue //images that contain blue
colors.blue>=2 //images that are at least 2% blue		 To search for images that contain a specified color (as one of the detected predominant colors), use the colon notation. Supported colors: green, blue, lightblue, black, white, red, gray, lime, yellow, olive, cyan, teal, purple, orange, pink, and brown
To search for images that have a specified % of the specified color, use the dot (.) notation.
Image resources only.

Note: The colors field is returned in searches including a with_field parameter specifying image_analysis.
etag String etag=d8ee49a7e9fb633c91cd4d4b2b Exact match only. Case-sensitive.

Note: The etag field is returned in searches including a with_field parameter specifying image_analysis.
face_count Number face_count>=1 Image resources only.

Note: The face_count field is returned in searches including a with_field parameter specifying image_analysis.
grayscale Boolean grayscale:true Image resources only.

Note: The grayscale field is returned in searches including a with_field parameter specifying image_analysis.
illustration_score Number illustration_score>0.5 The likelihood that the image is an illustration (as opposed to a photo). Values between 0 (photo) and 1 (illustration).
Image resources only.

Note: The illustration_score field is returned in searches including a with_field parameter specifying image_analysis.
image_metadata String image_metadata.license=a1s3d5f7a9s2d4f Accesses the specified type of embedded metadata from the image, such as from the Exif data or XMP.
Specify any embedded metadata element using the dot (.) notation.
Embedded metadata element values are case-sensitive. Specify their names exactly as stored inside the actual image metadata.
Image resources only.
location String location:"40.73,-74.1|41.73,-74.1|41.73,-75.1|42.73,-75.1|41.73,-74.1" // within a bounding polygon
location:"40.73,-74.1|40.73,-74.1" // within a bounding box
location:"40.73,-74.1 5km" // within distance of a point		 Matches the GPS location stored with the image metadata to within a specified bounding polygon, bounding box, or within distance from a specified point (distance can be specified in: mi (miles), yd (yards), m (meters), or km (kilometers)).
quality_analysis.color_score Number quality_analysis.color_score>0.6 A component of extended quality analysis, the quality_analysis.color_score takes into account factors such as exposure, white balance, contrast and saturation. Downscaling makes no difference to the perceived color quality. Available only for images for which quality_analysis was set to true during upload (in the upload request or upload preset).

Note: The quality_analysis.color_score field is returned in searches including a with_field parameter specifying quality_analysis.
quality_analysis.pixel_score Number quality_analysis.pixel_score>0.6 A component of extended quality analysis, the quality_analysis.pixel_score is a measure of how the image looks in terms of compression artifacts (blockiness, ringing etc.) and in terms of capture quality (focus and sensor noise). Downscaling can improve the perceived visual quality of an image with a poor pixel score. Available only for images for which quality_analysis was set to true during upload (in the upload request or upload preset).

Note: The quality_analysis.pixel_score field is returned in searches including a with_field parameter specifying quality_analysis.
quality_score Number quality_score>0.7 The overall weighted quality score. Available only for images for which quality_analysis was set to true during upload (in the upload request or upload preset) and only for paid accounts taking part in the extended quality analysis Beta trial.

Note: The quality_score field is returned in searches including a with_field parameter specifying image_analysis.
taken_at Date taken_at:[2017-10-10T12:00:00Z TO 1w]
taken_at:[1w TO 4w]
taken_at>10d
taken_at<1w
taken_at<=2016-01-01
taken_at<1486910712		 The date the photograph was taken according to the EXIF data.
transparent Boolean transparent:true Returns any asset where one or more pixels has an alpha channel. This doesn't necessarily mean there are any visibly transparent or semi-transparent areas in the image.
Image resources only.

Note: The transparent field is returned in searches including a with_field parameter specifying image_analysis.

Footnote
  1. When specifying a range, the results include all matches from and including the minimum number specified, and up to but not including the maximum number specified.

✔️ Feedback sent!

Rate this page: