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
type
optional
string
Limit search to either file or folder. Pass all to include both files and folders in search results. Default value - file
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 Default value - ASC_CREATED
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. type 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",
"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.

Basic examples

Basic usage
Using AND/OR operator
Grouping multiple queries
Basic usage

You can query based on a single field. For example:

createdAt > "7d"

This will return all files which are created in the last 7 days.

Using AND/OR operator

You can combine multiple conditions using the AND and OR operators. For example:

createdAt > "7d" AND name: "file-name"

This will return all files created within the last 7 days with name starting with file-name.

Grouping multiple queries

You can use parenthesis ( and ) to group multiple queries and create complex search filters. For example:

(size < "1mb" AND width > 500) OR (tags IN ["summer-sale","banner"])

Search based on file and folder names

For example, let's say you have uploaded two files red-dress-summer.jpg and red-dress-winter.jpg in the media library.

The name match is case-sensitive.

Exact match
Begins with match
Exact match

To find a file or folder using the exact name, use = operator. For example:

name = "red-dress-summer.jpg"

This will only return the file with the name red-dress-summer.jpg

Begins with match

To find a file or folder using a prefix, you can use : operator. For example:

name : "red-dress"

This will return both red-dress-summer.jpg and red-dress-winter.jpg.

Search based on upload date

You can filter using createdAt and updatedAt to search based on the first uploaded or last modified time.

createdAt and updatedAt accepts ISO 8601 format string or relative unit.

ISO 8601 format
Relative units
ISO 8601 format

The API supports a string in ISO 8601 format.

  • YYYY-MM-DD - When no time is provided, it is set to 00:00:00 UTC by default.

  • YYYY-MM-DDTHH:MM:SS

For example:

createdAt < 2020-01-01
createdAt < "2020-01-01T12:12:12"
Relative units

The API supports relative time units, e.g:

  • 1h - one hour in the past

  • 2d - two days in the past

  • Similarly 3w, 4m etc.

Example usage:

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)

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 tag set.

tags NOT IN ["big-banner"] will return all files that do not have big-banner tag set.

type

  • =

  • IN

  • NOT =

  • NOT IN

Possible values are file or folder in quotes or in the array.

type = "file" will only return files 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

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.

format

  • =

  • IN

Accepts a string value. Allowed values are jpg, webp, png, gif, svg, avif, pdf, js, woff2, woff, ttf, otf, eot, css, txt, mp4, webm, mov, swf, ts, m3u8, ico.

format = "jpg" will return all JPG image files.

private

  • =

Accepts a boolean value i.e. true or false without quotes.

private = true will return all files marked as private during upload.

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.

Understanding response

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.

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' \
-G --data-urlencode "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': '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 : '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' \
-G --data-urlencode "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' \
-G --data-urlencode "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"'})