List and search files

get
List and search file API

https://api.imagekit.io/v1/files
This API can list all the uploaded files and folders in your ImageKit.io media library. 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.
Request
Response
Request
Headers
Authorization
required
string
base64 encoding of your_private_api_key: Note the colon in the end.
Query Parameters
sort
optional
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
path
optional
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
optional
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. includeFolder 3. name
fileType
optional
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
optional
string
The maximum number of results to return in response: Minimum value - 1 Maximum value - 1000 Default value - 1000
skip
optional
string
The number of results to skip before returning results. Minimum value - 0 Default value - 0
Response
200: OK
[
{
"fileId" : "598821f949c0a938d57563bd",
"type": "file",
"name": "file1.jpg",
"filePath": "/images/products/file1.jpg",
"tags": ["t-shirt","round-neck","sale2019"],
"isPrivateFile" : false,
"customCoordinates" : null,
"url": "https://ik.imagekit.io/your_imagekit_id/images/products/file1.jpg",
"thumbnail": "https://ik.imagekit.io/your_imagekit_id/tr:n-media_library_thumbnail/images/products/file1.jpg",
"fileType": "image",
"mime": "image/jpeg",
"format": "jpeg",
"width": 100,
"height": 100,
"size": 100,
"hasAlpha": false,
"createdAt": "2019-08-24T06:14:41.313Z",
"updatedAt": "2019-08-24T06:14:41.313Z"
},
...more items
]

Advanced search queries

The searchQuery parameter can be used to apply advanced filters to your search. For example, the following search query would limit the search results to items created on or after a week ago and whose size is greater than 50 kb.

createdAt > 1w AND size > 50kb

Here is the complete list of parameters supported in searchQuery.

A few more examples:

1. Single Field

name = red_dress.jpg

Use the '=' (equals) operator when you want to find exact matches. The above query will return files whose name is exactly red_dress.jpg.

name : red

Use the ':' (colon) operator when you want to find matches with a specified prefix. The above query will return files whose name starts with the string 'red'. For example, both red-dress.jpg and red-shirt.png will be returned by the above query.

The Filename match is case-sensitive.

Similarly, the following table specifies all the possible operators on a single field:

Operator

What it does

Example

=

(equals)

Matches items with fields that are exactly equal to the specified value

name = red_dress.jpg

:

(colon)

Matches items with fields whose values begin with the specified value

name : red

<

(less than)

Matches items with fields whose values are less than the specified value

size < 10kb

<=

(less than equal)

Matches items with fields whose values are less than or equal to the specified value

size <= 10kb

>

(greater than)

Matches items with fields whose values are greater than the specified value

size > 1mb

>=

(greater than equal)

Matches items with fields whose values are greater than or equal to the specified value

size >= 1mb

IN (in operator)

Matches items with fields whose value is exactly equal to one of the specified values

color IN ["red", "blue"]

2. Combining multiple Fields using AND and OR operators

It is possible to combine multiple filters in a single query by combining them using boolean logical operators AND and OR.

size < 1mb AND width > 1000

The above query will return results for which the size is less than 1MB and the width is greater than 1000 px.

size < 1mb OR height < 5000

The above query will return results for which the size is less than 1MB, or the height is less than 5000 px.

It is also possible to create more complex queries using parenthesis. For example:

(size < 1mb AND width > 500) OR (size < 3mb AND height > 500)

Here, the expressions inside the parenthesis will be evaluated first and then combined using a logical OR operator.

3. NOT operator

You can specify the NOT operator preceding any other operator to negate that particular expression. For example:

color NOT IN ["red", "blue"]

The above query will return results for which the color field's value is not "red" or "blue".

4. Dates

You can specify dates (and times) in one of the following three formats:

  • YYYY-MM-DD (no time - when no time is provided, it is set to 00:00:00 UTC by default)

  • YYYY-MM-DD HH:MM:SS (date and time separated by a space)

  • YYYY-MM-DDTHH:MM:SS (date and time separated by a T)

Alternatively, you can use quantifiers for days, weeks, months, and years along with a number. 2d translates to the date that was two days ago. 2w translates to the date that was two weeks ago. And similarly for 2m, and 2y. For example, the following dates are all valid:

createdAt < 2020-01-01
createdAt < 2020-01-01T12:12:12
createdAt < 2020-01-01 12:12:12
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)

5. Arrays

Arrays of values can be specified as well, just with one restriction. All non-numeric values inside an array MUST be written within double-quotes.

This is a valid array value:

tags IN ["small", "inventory"] This is NOT a valid array value:

tags IN ['small', 'inventory']

Complete List of Parameters

Field

Operators Supported

Possible Values

name

= (equals), : (colon), IN (in operator)

Any string value(s).

type

= (equals), : (colon), IN (in operator)

"file" or "folder" or ["file", "folder"].

createdAt

= (equals), < (less than), <= (less than equal), > (greater than), >= (greater than equal), IN (in operator)

Any date value(s) in any of the formats specified above in the dates section.

updatedAt

= (equals), < (less than), <= (less than equal), > (greater than), >= (greater than equal), IN (in operator)

Any date value(s) in any of the formats specified above in the dates section.

height

= (equals), < (less than), <= (less than equal), > (greater than), >= (greater than equal), IN (in operator)

Any numeric value(s).

width

= (equals), < (less than), <= (less than equal), > (greater than), >= (greater than equal), IN (in operator)

Any numeric value(s).

size

= (equals), < (less than), <= (less than equal), > (greater than), >= (greater than equal), IN (in operator)

Any numeric value(s).

format

= (equals), : (colon), IN (in operator)

Supported formats: jpg, webp, png, gif, svg, avif, pdf, js, woff2, woff, ttf, otf, eot, css, txt, mp4, webm, mov, swf, ts, m3u8, ico

Example values: "jpg", ["jpg", "pdf"].

private

= (equals), : (colon), IN (in operator)

A boolean value i.e. true or false.

transparency

= (equals), : (colon), IN (in operator)

A boolean value i.e. true or false.

Response structure and status code (application/JSON)

In case of an error, you will get an error code along with the error message. On success, you will receive a 200 status code with the list of files in JSON-encoded response body.

Understanding response

The JSON-encoded response has an array of items. Each item can have the following properties.

Property name

Description

fileId

The unique fileId of the uploaded file.

type

Type of item. It can be either file or folder.

name

Name of the file or folder.

filePath

The relative path of the file. In the case of an image, you can use this path to construct different transformations.

tags

The array of tags associated with the image. If no tags are set, it will be null.

isPrivateFile

Is the file marked as private. It can be either true or false.

customCoordinates

Value of custom coordinates associated with the image in the format x,y,width,height. If customCoordinates are not defined, then it is null.

url

A publicly accessible URL of the file.

thumbnail

In the case of an image, a small thumbnail URL.

fileType

The type of file could be either image or non-image.

mime

MIME Type of the file. For example - image/jpeg

height

Height of the image in pixels (Only for images)

width

Width of the image in pixels (Only for Images)

size

Size of the image file in Bytes

hasAlpha

TODO

createdAt

The date and time when the file was first uploaded. The format is YYYY-MM-DDTHH:mm:ss.sssZ

updatedAt

The date and time when the file was last updated. The format is YYYY-MM-DDTHH:mm:ss.sssZ

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.

cURL
Node.js
Python
PHP
Java
Ruby
cURL
curl -X GET 'https://api.imagekit.io/v1/files?skip=0&limit=10' \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
skip : 0,
limit : 10
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"skip": 0, "limit": 10})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"skip" => 0,
"limit" => 10,
));
echo ("List files : " . json_encode($listFiles));
Java
Map<String , String> options=new HashMap<>();
options.put("skip","0");
options.put("limit", "10");
ResultList resultList=ImageKit.getInstance().getFileList(options);
Ruby
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
list_files = imagekitio.list_files({skip: 0, limit: 5})

Advance search using searchQuery

List all files uploaded in the last 7 days with a file size greater than 2MB. We will use the following value for searchQuery parameter.

createdAt >= 7d AND size > 2mb

cURL
Node.js
Python
PHP
Java
Ruby
cURL
curl -X GET 'https://api.imagekit.io/v1/files?searchQuery="createdAt >= 7d AND size > 2mb"' \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
searchQuery : 'createdAt >= 7d AND size > 2mb'
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({'searchQuery': 'name="createdAt >= 7d AND size > 2mb"'})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"searchQuery" => 'createdAt >= 7d AND size > 2mb',
));
echo ("List files : " . json_encode($listFiles));
Java
Map<String , String> options=new HashMap<>();
options.put("searchQquery",'createdAt >= 7d AND size > 2mb');
ResultList resultList=ImageKit.getInstance().getFileList(options);
Ruby
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
list_files = imagekitio.list_files({searchQuery : 'name="createdAt >= 7d AND size > 2mb"'})

Search media library files by name

List all files with filename file-name.jpg. We will use the following value of thesearchQuery parameter. The match is always case-sensitive.

name="file-name.jpg"

cURL
Node.js
Python
PHP
Java
Ruby
cURL
curl -X GET 'https://api.imagekit.io/v1/files?searchQuery=name="file-name.jpg"' \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
searchQuery : 'name="file-name.jpg"'
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({'searchQuery': 'name="file-name.jpg"'})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"searchQuery" => 'name="file-name.jpg"',
));
echo ("List files : " . json_encode($listFiles));
Java
Map<String , String> options=new HashMap<>();
options.put("searchQquery",'name="file-name.jpg"');
ResultList resultList=ImageKit.getInstance().getFileList(options);
Ruby
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
list_files = imagekitio.list_files({searchQuery : 'name="file-name.jpg"'})

List files within a specific folder

List all files at a specific location.

When using path parameter, the search is limited to only one level. The files within nested folders are not returned.

cURL
Node.js
Python
PHP
Java
Ruby
cURL
curl -X GET "https://api.imagekit.io/v1/files?path=products" \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
path : "products"
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"path": "products"})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"path" => "products",
));
echo ("List files : " . json_encode($listFiles));
Java
Map<String , String> options=new HashMap<>();
options.put("path","products");
ResultList resultList=ImageKit.getInstance().getFileList(options);
Ruby
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
list_files = imagekitio.list_files({path : "products"})

Simple search files by tags without using searchQuery

This will list all the files which have either sale or summer tag.

cURL
Node.js
Python
PHP
Java
Ruby
cURL
curl -X GET 'https://api.imagekit.io/v1/files?tags=sale,summer' \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
tags : ["sale","summer"]
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"tags": ["sale","summer"]})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"tags" => implode(",", array("sale", "summer")),
));
echo ("List files : " . json_encode($listFiles));
Java
Map<String , String> options=new HashMap<>();
options.put("tags","sale,summer");
ResultList resultList=ImageKit.getInstance().getFileList(options);
Ruby
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
list_files = imagekitio.list_files({tags : "sale,summer"})

Search all PNG files

This will list all PNG type files. We will use the following value of searchQuery

format="png"

cURL
Node.js
Python
PHP
Java
Ruby
cURL
curl -X GET 'https://api.imagekit.io/v1/files?searchQuery=format="png"' \
-u your_private_api_key:
Node.js
var ImageKit = require("imagekit");
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
imagekit.listFiles({
searchQuery : 'format="png"'
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
Python
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your_public_api_key',
public_key='your_private_api_key',
url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)
list_files = imagekit.list_files({"searchQuery": 'format="png"'})
print("List files-", "\n", list_files)
PHP
use ImageKit\ImageKit;
$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$listFiles = $imageKit->listFiles(array(
"searchQuery" => 'format="png"',
));
echo ("List files : " . json_encode($listFiles));
Java
Map<String , String> options=new HashMap<>();
options.put("searchQuery",'format="png"');
ResultList resultList=ImageKit.getInstance().getFileList(options);
Ruby
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
list_files = imagekitio.list_files({searchQuery : 'format="png"'})