Search API method

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.

Quick example

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:

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

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.

Search examples

1. Find assets containing 'shirt' 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 the next page of 500 results, using the 'next_cursor' from the previous call (b16b8bd80426df43a107f26b0348), of a search for images tagged with 'shirt', that have been uploaded within the last day, and sort the results by public_id in descending order:

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: