List assets
Last updated: Sep-02-2024
Cloudinary provides both client-side and server-side methods to list and get details on your assets.
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.
- 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.
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.
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:
- Get details of a single resource by public ID to get all details of an asset by its public ID.
- Get details of a single resource by asset ID to get all details of an asset by its immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type.
For example, to get the details of an asset with the public ID of 'hat', including faces and colors details: