Search API reference

Last updated: Nov-14-2022

Overview

The Cloudinary 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. A few examples of what you can accomplish using the search method include:

Searching by descriptive attributes such as public ID, filename, folders, tags, context, etc.
Searching by file details such as type, format, file size, dimensions, etc.
Searching by embedded data such as Exif, XMP, etc.
Searching by analyzed data such as the number of faces, predominant colors, auto-tags, etc.
Requesting aggregation counts on specified parameters, for example the number of assets found broken down by file format.

On this page:

Overview
Search method
Expressions
Expression Fields

Quick example

Find images tagged with 'kitten', that have been 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 resources:

Ruby PHP Python Node.js Java .NET Go Endpoint All

Ruby (cloudinary 1.x):

result = Cloudinary::Search
  .expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m')
  .sort_by('public_id','desc')
  .max_results(30)
  .execute

PHP (cloudinary_php 2.x):

$result = $cloudinary->searchApi()
  ->expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m')
  ->sortBy('public_id','desc')
  ->maxResults(30)
  ->execute();

PHP (cloudinary_php 1.x (legacy)):

$search = new \Cloudinary\Search();
$search->expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m');
$search->sort_by('public_id','desc');
$search->max_results(500);
$result = $search->execute();

Python (cloudinary 1.x):

result = cloudinary.Search()\
  .expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m')\
  .sort_by('public_id','desc')\
  .max_results('30')\
  .execute()

Node.js (cloudinary 1.x):

cloudinary.v2.search
  .expression('resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m')
  .sort_by('public_id','desc')
  .max_results(30)
  .execute()
  .then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.search()
  .expression("resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m")
  .sortBy("public_id","desc")
  .maxResults(30)
  .execute();

.NET (CloudinaryDotNet 1.x):

SearchResult result = cloudinary.Search()
  .Expression("resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m")
  .SortBy("public_id","desc")
  .MaxResults(30)
  .Execute();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Search(ctx, search.Query{
    Expression: "resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m",
    SortBy:     []search.SortByField{{"public_id": "desc"}},
    MaxResults: 30})

endpoint:

curl \
  -H "Content-Type: application/json" \
  -d '{
        "expression": "resource_type:image AND tags=kitten AND uploaded_at>1d AND bytes>1m",
        "sort_by": [{"public_id": "desc"}],
        "max_results":30
      }' \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search

cli:

cld search "resource_type=image AND tags=kitten AND uploaded_at>1d AND bytes>1m" -s public_id desc -n 30

Tiers

The Search API capabilities are divided into 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 is 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. Tier 2 is provided at an extra cost for Advanced plans. For Enterprise plans, Tier 2 functionality is included in the price of your package for up to 10 million assets (and available 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

Run in Postman Learn more about running Postman collections

The Search method enables you to find the specific assets in your product environment that meet your given criteria.

Note

The search method is part of the rate-limited Admin API, and shares the same usage limits. See that documentation for more information on authentication, pagination and error handling.

Syntax

GET /resources/search

Ruby PHP Python Node.js Java .NET Go CLI All

Ruby (cloudinary 1.x):

result = Cloudinary::Search.execute

PHP (cloudinary_php 2.x):

$result = $cloudinary->searchApi()->execute();

PHP (cloudinary_php 1.x (legacy)):

$result = \Cloudinary\search->execute();

Python (cloudinary 1.x):

result = cloudinary.Search().expression().execute()

Node.js (cloudinary 1.x):

cloudinary.v2.search.execute().then(callback);

Java (cloudinary 1.x):

result = cloudinary.search().execute();

.NET (CloudinaryDotNet 1.x):

SearchResult result = cloudinary.Search().Execute();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Search(ctx, search.Query{})

cli:

cld search

Note

Cloudinary implements eventual consistency: any changes made to assets will only be reflected in a search made a few seconds after the change is processed.

Parameters

All the parameters of the search method are optional. Including no parameters in the method call will return the 50 most recently created resources in descending order of creation time.

Parameter	Type	Description
expression	String	The (Lucene-like) string expression specifying the search query. If this parameter is not provided then all resources are listed (up to `max_results`). For details, see the expressions documentation.
sort_by	String[]	An array of string values representing a key value pair, where the key is the field to sort by and the value is the direction. Valid sort directions are `asc` or `desc`. If this parameter is not provided then the results are sorted by descending creation date. You can specify more than one `sort_by` parameter; results will be sorted according to the order of the fields provided.
max_results	Integer	Maximum number of assets to return (maximum=500). Default: `10`.
next_cursor	String	When a request has more results to return than `max_results`, the `next_cursor` value is returned as part of the response. You can then specify this value as the `next_cursor` parameter of the following request.
with_field	String	The name of an additional asset attribute to include for each asset in the response. You can specify more than one `with_field` parameter. Possible value: `context`, `tags`, and for Tier 2 also `metadata`, `image_metadata`, and `image_analysis`.
aggregate	String	(Tier 2 only) The name of a field (attribute) for which an aggregation count should be calculated and returned in the response. You can specify more than one `aggregate` parameter. Supported values: `resource_type`, `type`, `pixels` (only the image assets in the response are aggregated), `duration` (only the video assets in the response are aggregated), `format`, and `bytes`. For aggregation fields without discrete values, the results are divided into categories. For example: - `bytes` are divided into small (<500 kb), medium (500 kb - 5 mb), large (5 mb - 100 mb), and huge (>100 mb). - Video `duration` is divided into short (< 3 minutes), medium (3-12 min), and long (> 12 min).

Important

A new Search query object should be initialized for every distinct query executed. Please avoid reusing the same instance of a Search query object, as that might lead to unexpected behavior, especially when using the sort_by parameter.
When iterating through the results using the next_cursor parameter, the query should be reused without changing any of the other parameter values.
When making direct calls to the Cloudinary endpoint, make sure to pass any parameters using JSON (with Content-Type: application/json) as in the cURL examples on this page.

Examples

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

Ruby PHP Python Node.js Java .NET Go Endpoint All

Ruby (cloudinary 1.x):

result = Cloudinary::Search
  .expression('cat')
  .with_field('context')
  .with_field('tags')
  .max_results(10)
  .execute

PHP (cloudinary_php 2.x):

$result = $cloudinary->searchApi()
  ->expression('cat')
  ->withField('context')
  ->withField('tags')
  ->maxResults(10)
  ->execute();

PHP (cloudinary_php 1.x (legacy)):

$result = \Cloudinary\search
  ->expression('cat')
  ->with_field('context')
  ->with_field('tags')
  ->max_results(10)
  ->execute();

Python (cloudinary 1.x):

result = cloudinary.Search()\
  .expression('cat')\
  .with_field('context')\
  .with_field('tags')\
  .max_results('10')\
  .execute()

Node.js (cloudinary 1.x):

cloudinary.v2.search
  .expression('cat')
  .with_field('context')
  .with_field('tags')
  .max_results(10)
  .execute()
  .then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.search()
  .expression("cat")
  .withField("context")
  .withField("tags")
  .maxResults(10)
  .execute();

.NET (CloudinaryDotNet 1.x):

SearchResult result = cloudinary.Search()
  .Expression("cat")
  .WithField("context")
  .WithField("tags")
  .MaxResults(10)
  .Execute();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Search(ctx, search.Query{
          Expression: "cat",
          WithField:  []string{"tags", "context"},
          MaxResults: 10})

endpoint:

curl \
  -H "Content-Type: application/json" \
  -d '{
        "expression": "cat",
        "with_field": ["context", "tags"],
        "max_results": 10
      }' \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search

cli:

cld search "cat" -f context -f tags -n 10

Find assets containing 'cat' in any field but not 'kitten' 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:

Ruby PHP Python Node.js Java .NET Go Endpoint All

Ruby (cloudinary 1.x):

result = Cloudinary::Search
  .expression('cat AND -tags:kitten')
  .sort_by('public_id','desc')
  .aggregate('format')
  .execute

PHP (cloudinary_php 2.x):

$result = $cloudinary->searchApi()
  ->expression('cat AND -tags:kitten')
  ->sortBy('public_id','desc')
  ->aggregate('format')
  ->execute();

PHP (cloudinary_php 1.x (legacy)):

$result = \Cloudinary\search()
  ->expression('cat AND -tags:kitten')
  ->sort_by('public_id','desc')
  ->aggregate('format')
  ->execute();

Python (cloudinary 1.x):

result = cloudinary.Search()\
  .expression('cat AND -tags:kitten')\
  .sort_by('public_id','desc')\
  .aggregate('format')\
  .execute()

Node.js (cloudinary 1.x):

cloudinary.v2.search
  .expression('cat AND -tags:kitten')
  .sort_by('public_id','desc')
  .aggregate('format')
  .execute()
  .then(result=>console.log(result));

Java (cloudinary 1.x):

result = cloudinary.search()
  .expression("cat AND -tags:kitten")
  .sortBy("public_id","desc")
  .aggregate("format")
  .execute();

.NET (CloudinaryDotNet 1.x):

SearchResult result = cloudinary.Search()
  .Expression("cat AND -tags:kitten")
  .SortBy("public_id","desc")
  .Aggregate("format")
  .Execute();

Go (cloudinary-go 1.x):

resp, err := cld.Admin.Search(ctx, search.Query{
      Expression: "cat AND -tags:kitten",
      SortBy:     []search.SortByField{{"public_id": "desc"}},
      Aggregate:  []string{"format"},
      MaxResults: 2})

endpoint:

curl \
  -H "Content-Type: application/json" \
  -d '{
        "expression": "cat AND -tags:kitten",
        "sort_by": [{"public_id": "desc"}],
        "aggregate": ["format"]
      }' \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/search

cli:

cld search "cat AND -tags:kitten" -s public_id desc -a format

Tip

For more examples, see the expression examples documentation.

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:

{
  "total_count": 32,
  "time": 30,
  "aggregations": {
    "format": {
      "png": 4,
      "jpg": 21,
      "mp4": 3,
      "doc": 4
    }
  },
  "next_cursor": "b16b8bd80426df43a107f26b0348",
  "resources": [
  {
    "asset_id": "5f9d30acd36ac3c4f48a82241a37a299",
    "public_id": "sample",
    "folder": "",
    "filename": "sample",
    "format": "png",
    "version": 1492606756,
    "resource_type": "image",
    "type": "upload",
    "created_at": "2017-04-03T09:56:49+00:00",
    "uploaded_at": "2017-04-19T12:59:16+00:00",
    "bytes": 3381,
    "backup_bytes": 16905,
    "width": 241,
    "height": 51,
    "aspect_ratio": 4.7254901960784315,
    "pixels": 12291,
    "access_control": [       
     { access_type: "token" },
     { access_type: "anonymous", start: "2017-12-15T12:00Z", end: "2018-01-20T12:00Z" }],
    "context": {},
    "image_analysis": { 
      "face_count": 0,
      "faces": [],
      "grayscale": true,
      "illustration_score": 1,
      "transparent": false,
      "colors": {
        "gray": 96.7
      }
    },
    "url": "http://res.cloudinary.com/demo/image/upload/v1492606756/sample.png",
    "secure_url": "https://res.cloudinary.com/demo/image/upload/v1492606756/sample.png",
    "status": "active",
    "access_mode": "public"
  },
  {
    "public_id": "dog",
     …
     …
  }
  …
}

Expressions

The expression parameter in the search method describes the query string for filtering the assets in your product environment. A query string contains search terms that can be combined with Boolean operators to form a more complex query. You can also limit your search to specific fields or you can run your query on all fields.

If your search term contains a space or other reserved characters such as a colon, place the search term in quotes. For example, "hello dolly" or "16:9"

Important

The following special characters should be escaped with a backslash (\) in order to be used in a search expression or as a part of search term: ! ( ) { } [ ] * ^ ~ ? : \ = & > < and whitespace

For example: ~cat becomes \~cat

Fields

By default, the term is searched for in all the asset's string fields, except for strings with a value that is limited to a fixed list (e.g. access_mode is limited to the values 'public' or 'authenticated'). The search can be confined to a specific field (including fields not automatically included in the default search) by typing the field name followed by a colon : (or other relevant operator) and then the term you are looking for. For example, if you want to find assets of type "authenticated":

type:authenticated

Field names are case sensitive. For a list of supported fields, see Expression fields.

Field operators

When using fields in your query, you need to indicate the relationship between the search value and the field. For example, whether you are searching for assets where the field value is greater than, less than, or equal to the value you specify. The following operators are supported: : = > >= < <= [ ] { }

The supported operators and values you can use for a particular field depend on the type of that field, as detailed in Field types and supported operators.

String operators - exact or tokenized searches

Using the = operator finds matches where the value is an exact match.
Using the : operator finds matches where the value matches any complete token within the string value.

A token is a part of a search string that is separated by a separator character. Spaces, hyphens, and underscores are the most common characters that separate tokens within a search string. For example:

tags=cat

Finds a match only when the tag equals cat

tags:cat

Finds a match as long as any of the tokens in a tag entry includes cat, for example, tag values of cat and dog or dog-cat return as matches but catfish doesn't.

You can also append an asterisk (*) to the end of a search term in order to look for your search term as a prefix. For example, to search for "cat", "cats" or "catfish", you can use the search term:

tags=cat*

You can also combine the use of asterisks with exact (=) or tokenized (:) searches to further fine-tune your result:

If you only want to return results where the entire value starts with cat*, use an exact (=) search. For example, tags=cat*
If you want to return all results where any token in the value starts with cat*, use a tokenized (:) search. For example, tags:cat*

Notes

Some string fields support only exact matches. In these cases, even if you use a : operator, it will still behave as an exact match search. Fields that support exact match only are indicated in the Expression fields reference table.
The values of some string fields are case-sensitive, and some are a combination: case-sensitive when performing an exact (=) search and case-insensitive when performing a tokenized (:) search. Those that support exact match only are usually case-sensitive, while free text fields are either case-insensitive or a combination. The case sensitivity of each string field is indicated in the Expression fields reference table.
You cannot use the asterisk or token (:) operator to search for the middle or end of a string or token. For example, you cannot use *ple or :ple to find apple.

Range operators - inclusive or exclusive ranges

To search for a value that falls within a specific range, enclose the range values within square brackets to include the specified values or within curly braces to exclude the specified values, and separated with the TO operator. For example, to find assets with a file size within the range 1000 to 20000 bytes:

bytes:{1000 TO 20000}

You can also search for an alphabetic range, using any alphanumeric characters in your range query, for example, searching for public_ids with names that are alphabetically between "a" and "mz":

public_id:[a TO mz]

Boolean Operators

Boolean operators allow search terms to be combined through logic operators. Note that Boolean operators must be ALL CAPS.

Operator	Example	Description
`OR` or `\|\|`	tags:cat OR public_id:cat tags:cat \|\| public_id:cat tags:cat public_id:cat	Links two search terms and finds a match if either of the terms exist. This is the default operator for linking 2 terms.
`AND` or `&&`	tags:cat AND public_id:cat tags:cat && public_id:cat	Links two search terms and finds a match if both of the terms exist.
`+`	+cat +lion	Must have the term after the + symbol.
`NOT` or `!`	animals NOT lions animals !lions	Excludes assets that contain the term after NOT.
`-`	-animals -lions	Must not have the term after the - symbol.

Notes

Use parentheses to group terms to form sub-queries. This can be useful if you want to control the boolean logic for a query. For example, to search for either "cat" or "lion", and "animal" use the query:
(cat OR lion) AND animal
If only a single term is used in the expression without an operator then the + operator is implied. For example, the following expressions are identical:
animal
+animal
If part of the query evaluates to 'must have', either by using the + operator or by an intersection of 2 terms with the AND operator, then any additional terms linked with the OR operator will only be used for prioritizing the order of the results. For example, to search for "animals" and prioritize results that also have "cats":
+animals OR cats
+animals cats
By default, the search results do not include any assets currently in the 'pending' moderation status. If you want to include these assets in the results, you need to modify your query. For example:
animal AND moderation_status:pending
You can use the - operator with a specified structured metadata external_id, to search for assets with a structured metadata field that has no value set for that ID. For example, to search for all assets that have no value set for the metadata field with an ID of 'meta1':
-metadata=meta1

Expression examples

Assets containing "shirt" and with a tag that exactly matches "cotton":
Copy to clipboard
```
shirt AND tags=cotton
```
Images with a width between 200 and 1028, and an aspect_ratio of 16:9:
Copy to clipboard
```
resource_type:image AND width:{200 TO 1028} AND aspect_ratio:"16:9"
```
Originally created before January 15th 2017 and uploaded (overwritten) between 4 and 1 weeks ago:
Copy to clipboard
```
created_at<2017-01-15 AND uploaded_at:[4w TO 1w]
```
Uploaded less than 2 days ago and still pending moderation:
Copy to clipboard
```
uploaded_at>2d AND moderation_status:pending
```
PNG images with some transparency:
Copy to clipboard
```
format:png AND transparent:true
```
Images with more than 2 faces:
Copy to clipboard
```
resource_type:image AND face_count>2
```

Images larger than 10 MB or videos longer than 3 minutes:

(resource_type:image AND bytes>10000000) OR (resource_type:video AND duration>180)

Expression Fields

You can use the following fields to limit your 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.

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 are retrieved, such as when using the resources method.
`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:[2016-11-12T12:00:00Z TO 1w] created_at:[1w TO 4w] created_at>10d created_at<1w created_at<=2016-01-01 created_at<1486910712
`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.
`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 folder names 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	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]¹ 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]¹ 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 that is a measure of the 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 does not 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

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.

Field types and supported operators

Field type	Supported operators	Notes
Boolean	`=`	Possible values: `true`, `false`
Date	`= > >= < <= [ ] { }`	The date can be given as: - Unix time e.g., 1515911870 - UTC date (and optional time) in ISO8601 syntax: {yyyy-mm-dd}[T{hh:mm:ss}Z] - Relative time: a relative amount of time ago from today, such as an hour, day, week, month ago: 1h, 1d, 1w, 1m. Notes: - When specifying ranges, it is possible to specify each element of the range in a different date format. For example, a range from January the 15th 2016 until 1 week ago: created_at:[2016-01-15T12:00:00Z TO 1w]. The results for a range will include all matches from and including the minimum date specified, and up to but not including the maximum date specified. - When using operators such as greater than or less than with relative times, the comparison is in unix time. For example, 'greater than' indicates a unix time that is larger than the specified relative time. Therefore >3d indicates a date within the last 3 days.
Number	`= > >= < <= [ ] { }`
String	`: = [ ] { }`	Some string fields support both tokenized searches using the colon (:) operator, and exact searches using the equal sign (=) operator. Other fields support only exact searches. In these cases, regardless of whether you use a colon or equal sign operator, an exact search is performed. You can use the [ ] or { } range operators to search for strings falling into an alphabetical range. Note: The following string fields are not included in global searches. To search in these fields, you must explicitly specify the field in the search criteria: `type`, `status`, `resource_type`

✔️ Feedback sent!

✖️

Error

Unfortunately there's been an error sending your feedback.

Rate this page: