> ## Documentation Index > Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt > Use this file to discover all available pages before exploring further. # Search API method [search_response_link]: #search_response 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](admin_api#search_folders) API to search for folders that meet the criteria of a search expression. ## 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: ```multi |ruby result = Cloudinary::Search .expression('resource_type:image AND tags=shirt AND uploaded_at>1d AND bytes>1m') .sort_by('public_id','desc') .max_results(30) .execute |php_2 $result = $cloudinary->searchApi() ->expression('resource_type:image AND tags=shirt AND uploaded_at>1d AND bytes>1m') ->sortBy('public_id','desc') ->maxResults(30) ->execute(); |python result = cloudinary.Search()\ .expression("resource_type:image AND tags=shirt AND uploaded_at>1d AND bytes>1m")\ .sort_by("public_id","desc")\ .max_results("30")\ .execute() |nodejs cloudinary.v2.search .expression('resource_type:image AND tags=shirt AND uploaded_at>1d AND bytes>1m') .sort_by('public_id','desc') .max_results(30) .execute() .then(result=>console.log(result)); |java result = cloudinary.search() .expression("resource_type:image AND tags=shirt AND uploaded_at>1d AND bytes>1m") .sortBy("public_id","desc") .maxResults(30) .execute(); |csharp SearchResult result = cloudinary.Search() .Expression("resource_type:image AND tags=shirt AND uploaded_at>1d AND bytes>1m") .SortBy("public_id","desc") .MaxResults(30) .Execute(); |go resp, err := cld.Admin.Search(ctx, search.Query{ Expression: "resource_type:image AND tags=shirt AND uploaded_at>1d AND bytes>1m", SortBy: []search.SortByField{{"public_id": "desc"}}, MaxResults: 30}) |curl curl \ -H "Content-Type: application/json" \ -d '{ "expression": "resource_type:image AND tags=shirt AND uploaded_at>1d AND bytes>1m", "sort_by": [{"public_id": "desc"}], "max_results":30 }' \ https://:@api.cloudinary.com/v1_1//resources/search |cli cld search "resource_type=image AND tags=shirt AND uploaded_at>1d AND bytes>1m" -s public_id desc -n 30 ``` ## 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](https://support.cloudinary.com/hc/en-us/requests/new). * Tier 2 is available upon request for [Advanced plans](https://cloudinary.com/pricing) and higher. Advanced plans can use Tier 2 at an extra cost for Advanced plans. Customers on [Enterprise plans](https://cloudinary.com/pricing#pricing-enterprise) 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](https://support.cloudinary.com/hc/en-us/requests/new) to request the Tier 2 option. ## Search method The [Search for resources](admin_api#search_for_resources) method of the [Admin API](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](admin_api#search_for_resources_optional_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](#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](search_expressions) guide. For details on all the optional parameters of the search method, see the [Search method](admin_api#search_for_resources) 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](admin_api), and shares the same [usage limits](admin_api#usage_limits). See the Admin API documentation for more information on [authentication](admin_api#protocol_and_authentication), [pagination](admin_api#pagination) and [error handling](admin_api#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: ```multi |ruby result = Cloudinary::Search .expression('shoe') .fields('context') .fields('tags') .max_results(10) .execute |php_2 $result = $cloudinary->searchApi() ->expression('shoe') ->fields('context') ->fields('tags') ->maxResults(10) ->execute(); |python result = cloudinary.Search()\ .expression("shoe")\ .fields("context")\ .fields("tags")\ .max_results("10")\ .execute() |nodejs cloudinary.v2.search .expression('shoe') .fields('context') .fields('tags') .max_results(10) .execute() .then(result=>console.log(result)); |java result = cloudinary.search() .expression("shoe") .fields("context") .fields("tags") .maxResults(10) .execute(); |csharp SearchResult result = cloudinary.Search() .Expression("shoe") .Fields("context") .Fields("tags") .MaxResults(10) .Execute(); |go resp, err := cld.Admin.Search(ctx, search.Query{ Expression: "shoe", Fields: []string{"tags", "context"}, MaxResults: 10}) |curl curl \ -H "Content-Type: application/json" \ -d '{ "expression": "shoe", "fields": ["context", "tags"], "max_results": 10 }' \ https://:@api.cloudinary.com/v1_1//resources/search |cli cld search "shoe" -fi context -fi tags -n 10 ``` 1. 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: ```multi |ruby result = Cloudinary::Search .expression('shirt AND -tags:blue') .sort_by('public_id','desc') .aggregate('format') .execute |php_2 $result = $cloudinary->searchApi() ->expression('shirt AND -tags:blue') ->sortBy('public_id','desc') ->aggregate('format') ->execute(); |python result = cloudinary.Search()\ .expression("shirt AND -tags:blue")\ .sort_by("public_id","desc")\ .aggregate("format")\ .execute() |nodejs cloudinary.v2.search .expression('shirt AND -tags:blue') .sort_by('public_id','desc') .aggregate('format') .execute() .then(result=>console.log(result)); |java result = cloudinary.search() .expression("shirt AND -tags:blue") .sortBy("public_id","desc") .aggregate("format") .execute(); |csharp SearchResult result = cloudinary.Search() .Expression("shirt AND -tags:blue") .SortBy("public_id","desc") .Aggregate("format") .Execute(); |go resp, err := cld.Admin.Search(ctx, search.Query{ Expression: "shirt AND -tags:blue", SortBy: []search.SortByField{{"public_id": "desc"}}, Aggregate: []string{"format"}, MaxResults: 2}) |curl curl \ -H "Content-Type: application/json" \ -d '{ "expression": "shirt AND -tags:blue", "sort_by": [{"public_id": "desc"}], "aggregate": ["format"] }' \ https://:@api.cloudinary.com/v1_1//resources/search |cli cld search "shirt AND -tags:blue" -s public_id desc -a format ``` 1. 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](search_method#search_api_tiers) only) based on custom-defined ranges for the `bytes` (with ranges) and `format` attributes. (See a [sample response][search_response_link] for this example request.) ```multi |curl curl \ -H "Content-Type: application/json" \ -d '{ "expression": "clothing AND aspect_ratio < 1", "sort_by": [{"public_id": "desc"}], "aggregate": [ { "type": "bytes", "ranges": [ { "key": "tiny", "to": 500 }, { "key": "medium", "from": 501, "to": 1999 }, { "key": "big", "from": 2000 } ] }, "format" ] }' \ https://:@api.cloudinary.com/v1_1//resources/search ``` 1. 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: ```multi |ruby result = Cloudinary::Search .expression('resource_type:image AND tags=sale AND uploaded_at>1d') .sort_by('public_id','desc') .max_results(500) .next_cursor('b16b8bd80426df43a107f26b0348') .execute |php_2 $result = $cloudinary->searchApi() ->expression('resource_type:image AND tags=sale AND uploaded_at>1d') ->sortBy('public_id','desc') ->maxResults(500) ->nextCursor('b16b8bd80426df43a107f26b0348') ->execute(); |python result = cloudinary.Search()\ .expression("resource_type:image AND tags=sale AND uploaded_at>1d")\ .sort_by("public_id","desc")\ .max_results("500")\ .next_cursor("b16b8bd80426df43a107f26b0348")\ .execute() |nodejs cloudinary.v2.search .expression('resource_type:image AND tags=sale AND uploaded_at>1d') .sort_by('public_id','desc') .max_results(500) .next_cursor('b16b8bd80426df43a107f26b0348') .execute() .then(result=>console.log(result)); |java result = cloudinary.search() .expression("resource_type:image AND tags=sale AND uploaded_at>1d") .sortBy("public_id","desc") .maxResults(500) .nextCursor("b16b8bd80426df43a107f26b0348") .execute(); |csharp SearchResult result = cloudinary.Search() .Expression("resource_type:image AND tags=sale AND uploaded_at>1d") .SortBy("public_id","desc") .MaxResults(500) .NextCursor("b16b8bd80426df43a107f26b0348") .Execute(); |go resp, err := cld.Admin.Search(ctx, search.Query{ Expression: "resource_type:image AND tags=sale AND uploaded_at>1d", SortBy: []search.SortByField{{"public_id": "desc"}}, MaxResults: 500, NextCursor: 'b16b8bd80426df43a107f26b0348'}) |curl curl \ -H "Content-Type: application/json" \ -d '{ "expression": "resource_type:image AND tags=sale AND uploaded_at>1d", "sort_by": [{"public_id": "desc"}], "max_results":500, "next_cursor":"b16b8bd80426df43a107f26b0348" }' \ https://:@api.cloudinary.com/v1_1//resources/search |cli cld search "resource_type=image AND tags=sale AND uploaded_at>1d" -s public_id desc -n 500 next_cursor "b16b8bd80426df43a107f26b0348" ``` > **TIP**: For more examples, see the [expression examples](search_expressions#expression_examples) documentation. ## Search response The following example shows the response for Search [example #3](#aggregate_example_ranges) above, which includes a request for aggregation by bytes (with ranges) and by format (supported for[Tier 2](search_method#search_api_tiers) only). **Sample JSON Response**: ```json { "total_count": 201, "time": 1021, "aggregations": { "bytes": { "tiny": 10, "medium": 32, "big": 159 }, "format": { "mp4": 93, "jpg": 60, "png": 30, "webp": 9, "mkv": 2, "ts": 2, "unknown": 2, "avif": 1, "mov": 1, "webm": 1 } }, "next_cursor": "b16b8bd80426df43a107f26b0348", "resources": [ { "asset_id": "09169cf604b03521789d1b3b8cca53d1", "public_id": "blue_sweater", "asset_folder": "Clothing Sale", "filename": "blue_sweater", "display_name": "blue_sweater", "format": "jpg", "version": 1719316754, "resource_type": "image", "type": "upload", "created_at": "2024-06-25T11:59:14+00:00", "uploaded_at": "2024-06-25T11:59:14+00:00", "bytes": 71063, "backup_bytes": 71063, "width": 4800, "height": 6400, "aspect_ratio": 0.75, "pixels": 307200, "url": "http://res.cloudinary.com/cld-docs/image/upload/v1719316754/blue_sweater.jpg", "secure_url": "https://res.cloudinary.com/cld-docs/image/upload/v1719316754/blue_sweater.jpg", "status": "active", "access_mode": "public", "access_control": null, "etag": "7242da7b353e7da2c3eb8c006165b385", "created_by": { "access_key": "614335564976464" }, "uploaded_by": { "access_key": "614335564976464" } }, { "asset_id": "8e8fa813b32fdfb78cc6a53bdb21da32", "public_id": "yellow_sun_top", … … } … } ``` > **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](backups_and_version_management). ## 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](search_expressions#field_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_expressions#string_operators_exact_or_tokenized_searches) search unless otherwise specified. > **See also**: > > For a detailed overview and a variety of expression examples, see the [Search expressions](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 **Note**: The `access_mode` parameter is no longer supported. To restrict access to assets, you can use the `access_control` parameter. `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](admin_api#resources) method. Not supported for product environments using the legacy fixed folder mode. `asset_folder` | String | asset\_folder=test/sample // exact folder, no subfoldersasset\_folder:sample/* // prefix, all contents of 'sample' under rootasset\_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:shoecontext.productType=shoecontext."key with spaces":myValuecontext: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>10dcreated\_atcreated\_atcreated\_atlast\_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 subfoldersfolder:sample/* // prefix, all contents of 'sample' under rootfolder:"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\_idmetadata.name\_id:john //stringmetadata.city\_id=paris\_id //enummetadata.exp_date>2021-01-01 //datemetadata.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](admin_api#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/dogpublic\_id:test/sample/dogpublic\_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 searchtags=siamese //exact search-tags=siamese //doesn't have the tagtags="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_atMedia Properties ||| `aspect_ratio`|Number or String| aspect\_ratio="16:9"aspect\_ratioExact match only. Case-sensitive. `bytes` | Number | bytes:[1000 TO 5000000]1bytes>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]1duration>5durationdurationVideo 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 | height400000 | 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:imageresource\_type:video| Possible values: `image`, `video`, `raw` Exact match only. Case-sensitive. `width` | Number | width>100width=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=deletedstatus=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](backups_and_version_management).- 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](search_method#search_api_tiers)) ||| `accessibility_analysis.colorblind_accessibility_score` | Number | accessibility\_analysis.colorblind\_accessibility\_score>0.8 | A score between 0 and 1 indicating the level of [accessibility](accessibility_analysis) 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 bluecolors.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 brownTo 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 polygonlocation:"40.73,-74.1|40.73,-74.1" // within a bounding boxlocation:"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](image_quality_analysis#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](image_quality_analysis#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](image_quality_analysis#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>10dtaken\_attaken\_attaken\_atImage resources only. **Note**: The `transparent` field is returned in searches including a `with_field` parameter specifying `image_analysis`. > **NOTES**: :title=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.