Last updated: Nov-06-2023
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. A few examples of what you can accomplish using the
search API 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 per file format.
Find images tagged with 'shirt', 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 assets:
The Search API capabilities are divided into 2 tiers:
Tier 1: Includes support for using the
searchmethod 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 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.
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 query string for filtering the assets in a Lucene-like query language. 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. To learn about building search queries, see the search expressions guide.
If you don't include any parameters in the search method call, it will return the 50 most recently created assets in descending order of creation time.
Find assets containing 'shirt' in any field (attribute), include context metadata and tags in the details of each resource, and limit the returned results to 10 resources:
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:TipFor more examples, see the expression examples documentation.
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: