This API can list all the uploaded files and folders in your ImageKit.io media library. In addition, you can fine-tune your query by specifying various filters by generating a query string in a Lucene-like syntax and provide this generated string as the value of the searchQuery.
Query Parameters
Name
Type
Description
type
string
Limit search to one of file, file-version, or folder. Pass all to include files and folders in search results (file-version will not be included in this case).
Default value - file
sort
string
You can sort based on the following fields:
1. name - ASC_NAME or DESC_NAME
2. createdAt - ASC_CREATED or DESC_CREATED
3. updatedAt - ASC_UPDATED or DESC_UPDATED
4. height - ASC_HEIGHT or DESC_HEIGHT
5. width - ASC_WIDTH or DESC_WIDTH
6. size - ASC_SIZE or DESC_SIZE
Default value - ASC_CREATED
path
string
Folder path if you want to limit the search within a specific folder. For example, /sales-banner/ will only search in folder sales-banner.
searchQuery
string
Query string in a Lucene-like query language. Learn more about the query expression later in this section.
Note : When the searchQuery parameter is present, the following query parameters will have no effect on the result:
1. tags
2. type
3. name
fileType
string
Type of files to include in the result set. Accepts three values:
all - include all types of files in the result set.
image - only search in image type files.
non-image - only search in files that are not images, e.g., JS or CSS or video files.
Default value - all
limit
string
The maximum number of results to return in response:
Minimum value - 1
Maximum value - 1000
Default value - 1000
skip
string
The number of results to skip before returning results.
createdAt < 2d (createdAt should be before two days ago)
createdAt < 2w (createdAt should be before two weeks ago)
createdAt < 2m (createdAt should be before two months ago)
createdAt < 2y (createdAt should be before two years ago)
Search based on custom metadata or embedded metadata values
In your search query, you can use custom metadata and embedded metadata fields.
Every embedded metadata field must be prefixed with 'embeddedMetadata' and a period, and it must be enclosed within double quotes. For example, "embeddedMetadata.Keywords" IN ["black"]
Every custom metadata field must be prefixed with 'customMetadata' and a period, and it must be enclosed within double-quotes. For example, "customMetadata.description" IN ["black"]
Refer to the supported parameters table to see which embedded metadata values are supported and the corresponding supported operators and examples. The table also specifies the supported operators and examples corresponding to each custom metadata type.
Supported parameters
Field
Supported Operators
Examples
name
=
:
IN
NOT =
NOT IN
Accepts a string value in quotes. For example:
name = "red-dress.jpg" will return all
files & folders with the exact name red-dress.jpg.
name: "red-dress" will return all files & folders
with a name starting with red-dress.
name IN ["red-dress.jpg", "red-dress.png"] will return
all files & folders with the name either red-dress.jpg or
red-dress.png.
name NOT = "red-dress.jpg" will return all files and folders
with a name other than red-dress.jpg.
tags
IN
NOT IN
Accepts an array of string values.
tags IN ["summer-collection", "sale"] will return all files that have either summer-collection or sale inside either the tags array or the AITags array.
tags NOT IN ["big-banner"] will return all files that do not have big-banner inside neither the tags array nor the AITags array.
type
=
IN
NOT =
NOT IN
Possible values are file, file-version or folder in quotes or in the array.
type = "file" will only return files in the search result.
type = "file-version" will only return file versions in the search result.
type = "folder" will only return folders in the search result.
type IN ["file", "folder"] will return both files and folders in the search result.
createdAt
=
<
<=
>
>=
IN
NOT =
NOT IN
Accepts a string value in ISO 8601 format or relative time units e.g 1h, 2d, 3w, or 4m.
createdAt > "2020-01-01" will return all files first uploaded
after 1 Jan 2020 at 00:00 hours in UTC.
createdAt > "2020-01-01T12:12:12" will return all files first uploaded after 1 Jan 2020 12:12:12 hours in UTC.
createdAt > "7d" will return all files first uploaded in the last 7 days.
updatedAt
=
<
<=
>
>=
IN
NOT =
NOT IN
Accepts a string value in ISO 8601 format or relative time units e.g 1h, 2d, 3w, or 4m.
updatedAt > "2020-01-01" will return all files last modified
after 1 Jan 2020 at 00:00 hours in UTC.
updatedAt > "2020-01-01T12:12:12" will return all files last modified after 1 Jan 2020 12:12:12 hours in UTC.
updatedAt > "7d" will return all files last modified in the last 7 days.
height
=
<
<=
>
>=
IN
NOT =
NOT IN
Accepts a numeric value e.g. 500, 200 etc. This is only applicable for image-type assets.
height > 200 will return all image files with a height greater than 200px.
height <= 400 will return all image files with a height less than or equal to 400px.
width
=
<
<=
>
>=
IN
NOT =
NOT IN
Accepts a numeric value e.g. 500, 200 etc. This is only applicable for image-type assets.
width > 200 will return all image files with a width greater than 200px.
width <= 400 will return all image files with a width less than or equal to 400px.
size
=
<
<=
>
>=
IN
NOT =
NOT IN
Accepts a numeric value e.g. 500, 200 or string e.g. 1mb, 10kb etc.
size > 1024 will return all assets with a file size greater than 1024 bytes.
size <= "1mb" will return all assets with a file size less than or equal to 1MB.
Accepts a boolean value i.e. true or false without quotes.
private = true will return all files marked as private during upload.
published
=
Accepts a boolean value without quotes.
private = false will return all files that are in draft or unpublished state.
transparency
=
Accepts a boolean value i.e. true or false without quotes. This is only applicable to images.
transparency = true will return all image files that have an alpha layer. However, the presence of the alpha layer does not guarantee transparency if all pixels in the alpha layer have the value 1.
embeddedMetadata.LocationTaken
=
Accepts a location value in one of the supported types:
"40,100 5km" - Returns items that are within a 5 km distance from the specified coordinate
"40,100|50,105" - Returns items that are inside the square whose diagonal is the line made by the two specified points
"0,0|0,100|40,100|40,0" - Returns items that are inside the rectangle whose vertices are the four specified points.
Note: All coordinates are in the format latitude,longitude
embeddedMetadata.Keywords
IN
NOT IN
Accepts an array of string values.
"embeddedMetadata.Keywords" IN ["luxury", "dress"] will return all files that have either luxury or dress as one of the values in its Keywords field.
"embeddedMetadata.Keywords" NOT IN ["big-banner"] will return all files that do not have big-banner as one of the values in its Keywords field.
embeddedMetadata.DateTimeOriginal
=
<
<=
>
>=
IN
NOT =
NOT IN
Accepts a string value in ISO 8601 format or relative time units e.g 1h, 2d, 3w, or 4m.
"embeddedMetadata.DateTimeOriginal" > "2020-01-01" will return all files with a value later than 1 Jan 2020 at 00:00 hours in UTC.
"embeddedMetadata.DateTimeOriginal" > "2020-01-01T12:12:12" will return all files with a value later than 1 Jan 2020 12:12:12 hours in UTC.
"embeddedMetadata.DateTimeOriginal" > "7d" will return all files with a value that lies in the last 7 days.
Custom metadata Text type field
=
:
IN
NOT =
NOT IN
Accepts a string value in quotes. For example:
"customMetadata.description" = "black cars" will return all files & folders with the description custom field exactly equal to black cars.
"customMetadata.description": "red" will return all files & folders with the description custom field starting with red.
"customMetadata.description" IN ["red cars", "black cars"] will return all files & folders with the description custom field either red cars or
black cars.
"customMetadata.description" NOT = "red dress" will return all files and folders
with the description custom field other than red dress.
Custom metadata Textarea type field
=
:
IN
NOT =
NOT IN
Accepts a string value in quotes. For example:
"customMetadata.longDescription": "luxury" will return all files & folders with the longDescription custom field starting with luxury.
Custom metadata Date type field
=
<
<=
>
>=
IN
NOT =
NOT IN
Accepts a string value in ISO 8601 format or relative time units e.g 1h, 2d, 3w, or 4m.
"customMetadata.purchaseDate" > "2020-01-01" will return all files with a purchaseDate value later than 1 Jan 2020 at 00:00 hours in UTC.
"customMetadata.purchaseDate" > "2020-01-01T12:12:12" will return all files with a purchaseDate value later than 1 Jan 2020 12:12:12 hours in UTC.
"customMetadata.purchaseDate" > "7d" will return all files with a purchaseDate value that lies in the last 7 days.
Custom metadata Number type field
=
<
<=
>
>=
IN
NOT =
NOT IN
Accepts a numeric value e.g. 500, 200.125 , etc.
"customMetadata.quantitySold" > 200 will return all items with a quantitySold value greater than 200.
"customMetadata.quantitySold" <= 400 will return all items with a quantitySold value less than or equal to 400.
Custom metadata Boolean type field
=
Accepts a boolean value i.e. true or false without quotes.
"customMetadata.active" = true will return all items with an active value equal to true.
Custom metadata SingleSelect type
=
:
IN
NOT =
NOT IN
>
>=
<
<=
Accepts boolean, numeric, or string values.
"customMetadata.rating" = "excellent" will return all files with a rating value equal to excellent
"customMetadata.rating" > 4.3 will return all files that have a numeric rating value that is greater than 4.3
Note: certain operators will be valid only for certain types of values. For example, the >= operator will be valid only for numeric values.
Custom metadata MultiSelect type
IN
NOT IN
Accepts an array of boolean, numeric, or string values.
"customMetadata.tuple" IN ["luxury", 500, true] will return all files that have either luxury or 500 or true as one of the values in its tuples field.
"customMetadata.tuples" NOT IN ["big-banner"] will return all files that do not have big-banner as one of the values in its tuples field.
Understanding response
In case of an error, you will get an error code along with the error message. You will receive a 200 status code with the list of file object in the JSON-encoded response body on success.
Examples
Here are some example requests to understand the API usage.
Fetch 10 files uploaded in the media library
Fetch the first 10 files uploaded in the media library. To change the order, you can use sort option.
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
GetFileListRequest model = new GetFileListRequest
{
SearchQuery = "createdAt >= \"7d\""
};
ResultList res = imagekit.GetFileListRequest(model);
Custom metadata based search
List all files belonging to the clothing or accessories categories using a custom metadata field called category. The custom metadata schema for this field must have been defined first.
"customMetadata.category IN ["clothing", "accessories"]"
curl-XGET'https://api.imagekit.io/v1/files' \-G --data-urlencode"searchQuery=\"customMetadata.category\" IN [\"clothing\", \"accessories\"]" \-u your_private_api_key:
var ImageKit =require("imagekit");var imagekit =newImageKit({ publicKey :"your_public_api_key", privateKey :"your_private_api_key", urlEndpoint :"https://ik.imagekit.io/your_imagekit_id/"});imagekit.listFiles({ searchQuery :'"customMetadata.category" IN ["clothing", "accessories"]"'},function(error, result) { if(error) console.log(error);elseconsole.log(result);});
from imagekitio import ImageKitimagekit =ImageKit( public_key='your_public_api_key', private_key='your_private_api_key', url_endpoint ='https://ik.imagekit.io/your_imagekit_id/')list_files = imagekit.list_files(options=ListAndSearchFileRequestOptions(search_query='"customMetadata.category" IN ["clothing", "accessories"]"'))print("List files-", "\n", list_files)# Raw Responseprint(list_files.response_metadata.raw)# print the first file's IDprint(list_files.list[0].file_id)
GetFileListRequest getFileListRequest =newGetFileListRequest();getFileListRequest.setSearchQuery("'customMetadata.category' IN ['clothing', 'accessories']'");ResultList resultList =ImageKit.getInstance().getFileList(getFileListRequest);
imagekitio =ImageKitIo::Client.new("your_private_key","your_public_key","your_url_endpoint")list_files = imagekitio.list_files({search_query: '"customMetadata.category" IN ["clothing", "accessories"]"'})
resp, err := ik.Media.Files(ctx, media.FilesParam{ SearchQuery: `"customMetadata.category" IN ["clothing", "accessories"]"`,})
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
GetFileListRequest model = new GetFileListRequest
{
SearchQuery = '"customMetadata.category" IN ["clothing", "accessories"]"'
};
ResultList res = imagekit.GetFileListRequest(model);
Embedded metadata based search
List all files with a DateTimeOriginal value later than one year ago by using the embeddedMetadata.DateTimeOriginal field. i.e. all files that were originally created within the last one year.