Programmable Media
Menu

List assets

Last updated: Dec-11-2024

Cloudinary provides both client-side and server-side methods to list and get details on your assets.

On this page:

Client-side asset lists

You can use the list delivery type to generate a JSON listing of all assets with a specified tag directly from your front-end code. Additional information is returned for each asset, including information on its format, type, dimensions, contextual metadata and structured metadata.

URL syntax:

The response is a JSON snippet listing all the resources of the specified resource type and the specified tag. To return results for all images, videos and raw files with the same tag, you can specify a resource_type with a value of any.

For example, the request below generates a JSON list of all image resources in the demo project with the tag logo.

To generate the client-side lists using an SDK:

JSON response from the URL:

You can filter the list, so that only assets meeting certain criteria are returned in the response, by using a refine custom function.

Notes
  • By default, the list delivery type is restricted. To enable it, open the Security Settings in your Cloudinary Console, and clear the Resource list item under Restricted image types. You may want to clear this option only temporarily, as needed. Alternatively, you can bypass this (and any) delivery type restriction using a signed URL.
  • This option supports listing up to 1000 resources. To retrieve more than 1000, use the resources_by_tag property of the Admin API in server-side code, and include the next_cursor parameter to view long lists.
  • The JSON response is cached with a 60 second expiration policy. If you add or remove tags to assets, you'll be able to retrieve an updated JSON one minute after the previous JSON was generated.

Server-side asset lists

You can use the resources method to list the assets (resources) uploaded to your product environment.

Tip
The various params & methods available can be one way to return a set of assets that meet some criteria, but the Admin API search method offers far more flexibility with Lucene-like query expressions, and is usually the recommended way to find the set of assets you need.

The resources endpoint of the Admin API provides the following methods to list your assets: Get resources, Get resources by asset folder, Get resources by asset IDs, Get resources by tag, Get resources by context, and Get resources in moderation.

For example, to list all uploaded images with a prefix of shirt:

Details of a single asset

The resources endpoint of the Admin API also provides the methods to retrieve detailed information about a specific asset. These methods are useful when you need the data from the response to proceed to the next step of some function in your code. The details of the asset may include:

  • Semantic data extraction - Cloudinary supports extracting additional semantic data from the uploaded image such as: media metadata (including Exif, IPTC, XMP and GPS), color histogram, predominant colors, custom coordinates, pHash image fingerprint, ETag, and face and/or text coordinates.
  • Versions - Check the details of backed up versions of a specific asset.
  • Derived assets - The details of all the generated derived assets.
  • List related assets - The list of related assets to a specific asset.

You request the inclusion of this additional information in the upload response by including one or more optional parameters.

Tip
Whether or not you included a notification_url to get a response from another method, you can always use the Admin API's resource method to return the details of a resource.

The Admin API provides two methods to retrieve the details, either by public ID or by asset ID:

For example, to get the details of an asset with the public ID of 'hat', including faces and colors details:

✔️ Feedback sent!

Rate this page: