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"'})

📙API Reference - Previous

Media API

Get file details

Last updated 3 weeks ago

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"]

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

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`

List and search files

getList and search file API

Advanced search queries

1. Single Field

2. Combining multiple Fields using AND and OR operators

3. NOT operator

4. Dates

5. Arrays

Complete List of Parameters

Response structure and status code (application/JSON)

Understanding response

Examples

Fetch 10 files uploaded in the media library

Advance search using searchQuery

Search media library files by name

List files within a specific folder

Simple search files by tags without using searchQuery

Search all PNG files

get
List and search file API