> ## 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.

# List assets


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:

```
https://res.cloudinary.com/<your_cloud_name>/<resource_type>/list/<tag>.json
```

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`. 

> **TIP**: When specifying `any` as the resource_type, the generated JSON file is stored with a `resource_type` of `any`, while if specifying a specific resource type, the generated JSON file is stored with a `resource_type` of the specified resource type.  Knowing the `resource_type` of the generated JSON file can be relevant if you ever want to search for or delete the generated JSON file.

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

```
https://res.cloudinary.com/demo/image/list/logo.json
```

To generate the client-side lists using an SDK: 

```multi
|ruby
cloudinary_url("logo.json", type: "list")

|php_2
Media::fromParams("logo.json", ["type"=>"list"]);

|python
cloudinary_url("logo.json", type="list")

|nodejs
cloudinary.url("logo.json", {type: "list"})

|java
cloudinary.url().type("list").generate("logo.json");

|js
cloudinary.url('logo.json', {type: "list"});

|jquery
$.cloudinary.url("logo.json", {type: "list"})

|csharp
cloudinary.Api.UrlImgUp.Type("list").BuildImageTag("logo.json")

|go
myList, err := cld.Media("logo.json")
myList.DeliveryType = "list"
url, err := myList.String()

|android
MediaManager.get().url().type("list").generate("logo.json");

|swift
imageView.cldSetImage(cloudinary.createUrl().setType( "list").generate("logo.json")!, cloudinary: cloudinary)

|cli
cld url "logo" -t list
```

**JSON response from the URL**:

```json
 {"resources":
   [{"public_id":"cloudinary_fashion_logo","version":1588962712,"format":"png",
     "width":240,"height":307,"type":"upload","created_at":"2020-05-08T18:31:52Z",
     "metadata":[{"external_id":"color_id","label":"Colors","type":"set","value":
     [{"external_id":"color1","value":"red"},{"external_id":"color2","value":"green"}]}]},
   {"public_id":"amazon_logo","version":1315740184,"format":"png",
     "width":162,"height":38,"type":"upload","created_at":"2011-09-11T11:23:04Z"},
   {"public_id":"microsoft_logo","version":1315740090,"format":"png",
     "width":216,"height":70,"type":"upload","created_at":"2011-09-11T11:21:30Z"},
   {"public_id":"apple_logo","version":1315740074,"format":"jpg",
     "width":206,"height":250,"type":"upload","created_at":"2011-09-11T11:21:14Z",
     "context":{"custom":{"Main":"true","Order":"2"}}},
   {"public_id":"google_logo","version":1315740052,"format":"png",
     "width":275,"height":95,"type":"upload","created_at":"2011-09-11T11:20:52Z",
     "context":{"custom":{"alt":"google logo","caption":"Google Logo"}}}], 
     "updated_at":"2020-05-08T21:11:37Z"}
 ``` 

You can filter the list, so that only assets meeting certain criteria are returned in the response, by using a `refine` [custom function](custom_functions#refine_custom_functions). 

> **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](admin_api#get_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](admin_api#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](search_method#search_method) 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](admin_api#get_resources), [Get resources by asset folder](admin_api#get_resources_by_asset_folder), [Get resources by asset IDs](admin_api#get_resources_by_asset_ids), [Get resources by tag](admin_api#get_resources_by_tag), [Get resources by context](admin_api#get_resources_by_context), and [Get resources in moderation](admin_api#get_resources_in_moderation).

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

```multi
|curl
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload?prefix=shirt

|ruby
result = Cloudinary::Api
.resources(
type: "upload", 
prefix: "shirt")

|php_2
$result = $api
->assets([
  "type" => "upload", 
  "prefix" => "shirt"]);

|python
result = cloudinary.api\
.resources(
type = "upload", 
prefix = "shirt")

|nodejs
cloudinary.v2.api
.resources(
{ type: 'upload', 
  prefix: 'shirt' })
.then(result=>console.log(result)); 

|java
result = api
.resources(
ObjectUtils.asMap(
  "type", "upload", 
  "prefix", "shirt"));

|csharp
var listResourcesByPrefixParams = new ListResourcesByPrefixParams(){
  Type = "upload",
  Prefix = "shirt"};
var listResourcesResult = cloudinary.ListResources(listResourcesByPrefixParams);

|go
resp, err := cld.Admin.Assets(ctx, admin.AssetsParams{
        DeliveryType: "upload",
        Prefix:       "shirt"})

|cli
cld admin resources type=upload prefix=shirt
```
> **INFO**: The default resource type for most API requests is `image`. When working with videos, remember to explicitly set the `resource_type` to `video`.

### 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](semantic_data_extraction) 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](backups_and_version_management) of a specific asset.
* Derived assets - The details of all the generated [derived assets](cloudinary_glossary#derived_asset).
* List related assets - The list of [related assets](relate_assets) to a specific asset.

You request the inclusion of this additional information in the upload response by including one or more [optional parameters](admin_api#get_the_details_of_a_single_resource_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](admin_api#get_details_of_a_single_resource_by_public_id) 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](admin_api#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](admin_api#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:

```multi
|curl
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/resources/image/upload/sample?faces=1&colors=1&media_metadata=1&versions=1
        
|ruby
result = Cloudinary::Api
.resource('sample',
  faces: true, 
  colors: true)

|php_2
$result = $api
->asset("sample", [
    "faces" => true, 
    "colors" => true]);

|python
result = cloudinary.api\
.resource("sample",
  faces = True, 
  colors = True)

|nodejs
cloudinary.v2.api
.resource('sample', 
  { faces: true, 
    colors: true })
.then(result=>console.log(result)); 

|java
result = api
.resource("sample", 
  ObjectUtils.asMap(
    "faces", true,
    "colors", true));

|csharp
var getResource = new GetResourceParams("sample"){
  Faces = true,
  Colors = true };
var info = cloudinary.GetResource(getResource);

|go
resp, err := cld.Admin.Asset(ctx, admin.AssetParams{
        PublicID:       "sample",
        Faces:          api.Bool(true),
        Colors:         api.Bool(true)})

|cli
cld admin resource sample faces=true colors=true
```