> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# List of files

GET https://api.uploadcare.com/files/

Getting a paginated list of files. If you need multiple results pages, use `previous`/`next` from the response to navigate back/forth.

Reference: https://uploadcare.com/docs/api/rest/file/files-list

## Authentication

- `Authorization` header (required) — Every request made to `https://api.uploadcare.com/` MUST be signed. HTTPS SHOULD be used with any authorization scheme. Requests MUST contain the `Authorization` header defining `auth-scheme` and `auth-param`: `Authorization: auth-scheme auth-param`. Every request MUST contain the `Accept` header identifying the REST API version: `Accept: application/vnd.uploadcare-v0.7+json`. There are two available authorization schemes: * For production: `Uploadcare`, a scheme where a `signature`, not your Secret API Key MUST be specified. Signatures SHOULD be generated on backend. * For quick tests: `Uploadcare.Simple`, a simple scheme where your [Secret API Key](https://app.uploadcare.com/projects/-/api-keys/) MUST be specified in every request's `auth-param`.

## Request

### Query parameters

- `removed` (boolean, optional, default: false) — `true` to only include removed files in the response, `false` to include existing files. Defaults to `false`.
- `stored` (boolean, optional) — `true` to only include files that were stored, `false` to include temporary ones. The default is unset: both stored and not stored files are returned.
- `limit` (integer, optional, default: 100) — A preferred amount of files in a list for a single response. Defaults to 100, while the maximum is 1000.
- `ordering` (enum, optional, default: datetime_uploaded) — Specifies the way files are sorted in a returned list. `datetime_uploaded` for ascending order, `-datetime_uploaded` for descending order.
  - Allowed values: `datetime_uploaded`, `-datetime_uploaded`
- `from` (string, optional) — A starting point for filtering the files. If provided, the value MUST adhere to the ISO 8601 Extended Date/Time Format (`YYYY-MM-DDTHH:MM:SSZ`).
- `include` (string, optional) — Include additional fields to the file object, such as: appdata.

### Headers

- `Accept` (string, required) — Version header.

## Response

### 200

A list of files, paginated.

- `next` (string, optional, nullable) — Next page URL.
- `previous` (string, optional, nullable) — Previous page URL.
- `total` (integer, optional) — Total number of the files of the queried type. The queried type depends on the stored and removed query parameters.
- `totals` (FilesGetResponsesContentApplicationJsonSchemaTotals, optional)
- `per_page` (integer, optional) — Number of the files per page.
- `results` (list of file, optional)

## Errors

### 400 Bad Request Error

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

- `detail` (string, optional, default: Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.)

### 401 Unauthorized Error

Authorization errors.

- `detail` (enum, optional)
  - Allowed values: `Incorrect authentication credentials.`, `Public key {public_key} not found.`, `Secret key not found.`, `Invalid signature. Please check your Secret key.`

### 406 Not Acceptable Error

Invalid version header `Accept` for this endpoint.

- `detail` (string, optional, default: Incorrect Accept header provided. Make sure to specify API version. Refer to REST API docs for details.)

### 429 Too Many Requests Error

Request was throttled.

- `detail` (string, optional)

## Types

### FilesGetResponsesContentApplicationJsonSchemaTotals

- `removed` (integer, required, default: 0) — Total number of the files that are marked as removed.
- `stored` (integer, required, default: 0) — Total number of the files that are marked as stored.
- `unstored` (integer, required, default: 0) — Total number of the files that are not marked as stored.

### file

- `datetime_removed` (datetime, required, nullable) — Date and time when a file was removed, if any.
- `datetime_stored` (datetime, required, nullable) — Date and time of the last store request, if any.
- `datetime_uploaded` (datetime, required) — Date and time when a file was uploaded.
- `is_image` (boolean, required) — Is file is image.
- `is_ready` (boolean, required) — Is file is ready to be used after upload.
- `mime_type` (string, required) — File MIME-type.
- `original_file_url` (string, required, nullable) — Publicly available file CDN URL. Available if a file is not deleted.
- `original_filename` (string, required) — Original file name taken from uploaded file.
- `size` (integer, required) — File size in bytes.
- `url` (string, required) — API resource URL for a particular file.
- `uuid` (string, required) — File UUID.
- `variations` (map from string to string, required, nullable) — Dictionary of other files that were created using this file as a source. It's used for video processing and document conversion jobs. E.g., `<conversion_path>: <uuid>`.
- `content_info` (contentInfo, required) — Information about file content.
- `metadata` (metadata, required) — Arbitrary metadata associated with a file.
- `appdata` (applicationDataObject, optional) — Dictionary of application names and data associated with these applications.
- `tags` (list of string, optional) — Ordered list of string tags associated with the file. Empty array if no tags are set.

### contentInfo

Information about file content.

- `mime` (ContentInfoMime, optional) — MIME type.
- `image` (imageInfo, optional) — Image metadata.
- `video` (videoInfo, optional) — Video metadata.

### metadata

Arbitrary metadata associated with a file.

### applicationDataObject

Dictionary of application names and data associated with these applications.

- `aws_rekognition_detect_labels` (awsRekognitionDetectLabels_v2016_06_27, optional)
- `aws_rekognition_detect_moderation_labels` (awsRekognitionDetectModerationLabels_v2016_06_27, optional)
- `remove_bg` (removeBg_v1_0, optional)
- `uc_clamav_virus_scan` (ucClamavVirusScan, optional)

### ContentInfoMime

MIME type.

- `mime` (string, required) — Full MIME type.
- `type` (string, required) — Type of MIME type.
- `subtype` (string, required) — Subtype of MIME type.

### imageInfo

Image metadata.

- `color_mode` (enum, required) — Image color mode.
  - Allowed values: `RGB`, `RGBA`, `RGBa`, `RGBX`, `L`, `LA`, `La`, `P`, `PA`, `CMYK`, `YCbCr`, `HSV`, `LAB`
- `orientation` (integer, required, nullable) — Image orientation from EXIF.
- `format` (string, required) — Image format.
- `sequence` (boolean, required) — Set to true if a file contains a sequence of images (GIF for example).
- `height` (integer, required) — Image height in pixels.
- `width` (integer, required) — Image width in pixels.
- `geo_location` (ImageInfoGeoLocation, required, nullable) — Geo-location of image from EXIF.
- `datetime_original` (datetime, required, nullable) — Image date and time from EXIF. Please be aware that this data is not always formatted and displayed exactly as it appears in the EXIF.
- `dpi` (list of double, required, nullable) — Image DPI for two dimensions.

### videoInfo

Video metadata.

- `duration` (integer, required, nullable) — Video file's duration in milliseconds.
- `format` (string, required) — Video file's format.
- `bitrate` (integer, required, nullable) — Video file's bitrate.
- `audio` (list of VideoInfoAudioItems, required)
- `video` (list of VideoInfoVideoItems, required)

### awsRekognitionDetectLabels_v2016_06_27

- `version` (enum, required) — An application version.
  - Allowed values: `2016-06-27`
- `datetime_created` (datetime, required) — Date and time when an application data was created.
- `datetime_updated` (datetime, required) — Date and time when an application data was updated.
- `data` (AwsRekognitionDetectLabelsV20160627Data, required) — Dictionary with a result of an aws rekognition detect labels execution result.

### awsRekognitionDetectModerationLabels_v2016_06_27

- `version` (enum, required) — An application version.
  - Allowed values: `2016-06-27`
- `datetime_created` (datetime, required) — Date and time when an application data was created.
- `datetime_updated` (datetime, required) — Date and time when an application data was updated.
- `data` (AwsRekognitionDetectModerationLabelsV20160627Data, required) — Dictionary with a result of an aws rekognition detect moderation labels execution result.

### removeBg_v1_0

- `version` (enum, required) — An application version.
  - Allowed values: `1.0`
- `datetime_created` (datetime, required) — Date and time when an application data was created.
- `datetime_updated` (datetime, required) — Date and time when an application data was updated.
- `data` (RemoveBgV10Data, required) — Dictionary with a result of an remove.bg information about an image.

### ucClamavVirusScan

- `version` (enum, required) — An application version.
  - Allowed values: `0.104.2`, `0.104.3`, `0.105.0`, `0.105.1`
- `datetime_created` (datetime, required) — Date and time when an application data was created.
- `datetime_updated` (datetime, required) — Date and time when an application data was updated.
- `data` (UcClamavVirusScanData, required) — Dictionary with a result of ClamAV execution result.

### ImageInfoGeoLocation

Geo-location of image from EXIF.

- `latitude` (double, required) — Location latitude.
- `longitude` (double, required) — Location longitude.

### VideoInfoAudioItems

Audio stream's metadata.

- `bitrate` (integer, required, nullable) — Audio stream's bitrate.
- `codec` (string, required, nullable) — Audio stream's codec.
- `sample_rate` (integer, required, nullable) — Audio stream's sample rate.
- `channels` (integer, required, nullable) — Audio stream's number of channels.

### VideoInfoVideoItems

Video stream's metadata.

- `height` (integer, required) — Video stream's image height.
- `width` (integer, required) — Video stream's image width.
- `frame_rate` (double, required) — Video stream's frame rate.
- `bitrate` (integer, required, nullable) — Video stream's bitrate.
- `codec` (string, required, nullable) — Video stream's codec.

### AwsRekognitionDetectLabelsV20160627Data

Dictionary with a result of an aws rekognition detect labels execution result.

- `LabelModelVersion` (string, required)
- `Labels` (list of AwsRekognitionDetectLabelsV20160627DataLabelsItems, required)

### AwsRekognitionDetectModerationLabelsV20160627Data

Dictionary with a result of an aws rekognition detect moderation labels execution result.

- `ModerationModelVersion` (string, required)
- `ModerationLabels` (list of AwsRekognitionDetectModerationLabelsV20160627DataModerationLabelsItems, required)

### RemoveBgV10Data

Dictionary with a result of an remove.bg information about an image.

- `foreground_type` (string, optional) — foreground classification type (present if type_level was set)

### UcClamavVirusScanData

Dictionary with a result of ClamAV execution result.

- `infected` (boolean, required)
- `infected_with` (string, optional)

### AwsRekognitionDetectLabelsV20160627DataLabelsItems

- `Confidence` (double, required)
- `Instances` (list of AwsRekognitionDetectLabelsV20160627DataLabelsItemsInstancesItems, required)
- `Name` (string, required)
- `Parents` (list of AwsRekognitionDetectLabelsV20160627DataLabelsItemsParentsItems, required)

### AwsRekognitionDetectModerationLabelsV20160627DataModerationLabelsItems

- `Confidence` (double, required)
- `Name` (string, required)
- `ParentName` (string, required)

### AwsRekognitionDetectLabelsV20160627DataLabelsItemsInstancesItems

- `BoundingBox` (AwsRekognitionDetectLabelsV20160627DataLabelsItemsInstancesItemsBoundingBox, optional)
- `Confidence` (double, optional)

### AwsRekognitionDetectLabelsV20160627DataLabelsItemsParentsItems

- `Name` (string, optional)

### AwsRekognitionDetectLabelsV20160627DataLabelsItemsInstancesItemsBoundingBox

- `Height` (double, optional)
- `Left` (double, optional)
- `Top` (double, optional)
- `Width` (double, optional)

## Examples

### With App Data

**Response**

```json
{
  "next": "https://api.uploadcare.com/files/?limit=1&from=2018-11-27T01%3A00%3A43.001705%2B00%3A00&offset=0",
  "previous": "https://api.uploadcare.com/files/?limit=1&to=2018-11-27T01%3A00%3A36.436838%2B00%3A00&offset=0",
  "total": 2484,
  "totals": {
    "removed": 0,
    "stored": 2480,
    "unstored": 4
  },
  "per_page": 1,
  "results": [
    {
      "datetime_removed": null,
      "datetime_stored": "2018-11-26T12:49:10.477888Z",
      "datetime_uploaded": "2018-11-26T12:49:09.945335Z",
      "is_image": true,
      "is_ready": true,
      "mime_type": "image/jpeg",
      "original_file_url": "https://ucarecdn.com/22240276-2f06-41f8-9411-755c8ce926ed/pineapple.jpg",
      "original_filename": "pineapple.jpg",
      "size": 642,
      "url": "https://api.uploadcare.com/files/22240276-2f06-41f8-9411-755c8ce926ed/",
      "uuid": "22240276-2f06-41f8-9411-755c8ce926ed",
      "variations": null,
      "content_info": {
        "mime": {
          "mime": "image/jpeg",
          "type": "image",
          "subtype": "jpeg"
        },
        "image": {
          "color_mode": "RGB",
          "orientation": 6,
          "format": "JPEG",
          "sequence": false,
          "height": 500,
          "width": 500,
          "geo_location": {
            "latitude": 55.62013611111111,
            "longitude": 37.66299166666666
          },
          "datetime_original": "2018-08-20T08:59:50",
          "dpi": [
            72,
            72
          ]
        }
      },
      "metadata": {
        "pet": "cat",
        "subsystem": "uploader"
      },
      "appdata": {
        "uc_clamav_virus_scan": {
          "version": "0.104.2",
          "datetime_created": "2021-09-21T11:24:33.159663Z",
          "datetime_updated": "2021-09-21T11:24:33.159663Z",
          "data": {
            "infected": true,
            "infected_with": "Win.Test.EICAR_HDB-1"
          }
        }
      }
    }
  ]
}
```

**SDK Code**

```javascript JS
import {
  listOfFiles,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await listOfFiles(
  {},
  { authSchema: uploadcareSimpleAuthSchema }
)

```

```php PHP
<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);

$api = (new Uploadcare\Api($configuration))->file();
$list = $api->listFiles();
foreach ($list->getResults() as $result) {
    echo \sprintf('URL: %s', $result->getUrl());
}
while (($next = $api->nextPage($list)) !== null) {
    foreach ($next->getResults() as $result) {
        echo \sprintf('URL: %s', $result->getUrl());
    }
}

```

```python Python
from pyuploadcare import Uploadcare
uploadcare = Uploadcare(public_key='YOUR_PUBLIC_KEY', secret_key='YOUR_SECRET_KEY')

files = uploadcare.list_files(stored=True, limit=10)
for file in files:
    print(file.info)

```

```ruby Ruby
require 'uploadcare'
Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'

list = Uploadcare::FileList.file_list(stored: true, removed: false, limit: 100)
list.each { |file| puts file.inspect }

```

```swift Swift
import Uploadcare

let uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")

let query = PaginationQuery()
  .stored(true)
  .ordering(.dateTimeUploadedDESC)
  .limit(10)
var list = uploadcare.listOfFiles()

try await list.get(withQuery: query)
print(list)

// Next page
if list.next != nil {
  try await list.nextPage()
  print(list)
}

// Previous page
if list.previous != nil {
  try await filesList.previousPage()
  print(list)
}

```

```kotlin Kotlin
import com.uploadcare.android.library.api.UploadcareClient

val uploadcare = UploadcareClient(publicKey = "YOUR_PUBLIC_KEY", secretKey = "YOUR_SECRET_KEY")

val filesQueryBuilder = uploadcare.getFiles()
val files = filesQueryBuilder
    .stored(true)
    .ordering(Order.UPLOAD_TIME_DESC)
    .asList()
Log.d("TAG", files.toString())

```

```go With App Data
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.uploadcare.com/files/?from=2015-09-10T10%3A00%3A00Z&include=appdata&limit=100&ordering=-datetime_uploaded&removed=true&stored=true"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "application/vnd.uploadcare-v0.7+json")
	req.Header.Add("Authorization", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```java With App Data
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.uploadcare.com/files/?from=2015-09-10T10%3A00%3A00Z&include=appdata&limit=100&ordering=-datetime_uploaded&removed=true&stored=true")
  .header("Accept", "application/vnd.uploadcare-v0.7+json")
  .header("Authorization", "<apiKey>")
  .asString();
```

```csharp With App Data
using RestSharp;

var client = new RestClient("https://api.uploadcare.com/files/?from=2015-09-10T10%3A00%3A00Z&include=appdata&limit=100&ordering=-datetime_uploaded&removed=true&stored=true");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/vnd.uploadcare-v0.7+json");
request.AddHeader("Authorization", "<apiKey>");
IRestResponse response = client.Execute(request);
```

### Without App Data

**Response**

```json
{
  "next": "https://api.uploadcare.com/files/?limit=1&from=2018-11-27T01%3A00%3A43.001705%2B00%3A00&offset=0",
  "previous": "https://api.uploadcare.com/files/?limit=1&to=2018-11-27T01%3A00%3A36.436838%2B00%3A00&offset=0",
  "total": 2484,
  "totals": {
    "removed": 0,
    "stored": 2480,
    "unstored": 4
  },
  "per_page": 1,
  "results": [
    {
      "datetime_removed": null,
      "datetime_stored": "2021-09-21T11:24:33.159663Z",
      "datetime_uploaded": "2021-09-21T11:24:33.159663Z",
      "is_image": false,
      "is_ready": true,
      "mime_type": "video/mp4",
      "original_file_url": "https://ucarecdn.com/7ed2aed0-0482-4c13-921b-0557b193edc2/16317390663260.mp4",
      "original_filename": "16317390663260.mp4",
      "size": 14479722,
      "url": "https://api.uploadcare.com/files/7ed2aed0-0482-4c13-921b-0557b193edc2/",
      "uuid": "7ed2aed0-0482-4c13-921b-0557b193edc2",
      "variations": null,
      "content_info": {
        "mime": {
          "mime": "video/mp4",
          "type": "video",
          "subtype": "mp4"
        },
        "video": {
          "duration": 200044,
          "format": "mp4",
          "bitrate": 579,
          "audio": [
            {
              "bitrate": 129,
              "codec": "aac",
              "sample_rate": 44100,
              "channels": 2
            }
          ],
          "video": [
            {
              "height": 480,
              "width": 640,
              "frame_rate": 30,
              "bitrate": 433,
              "codec": "h264"
            }
          ]
        }
      },
      "metadata": {
        "pet": "dog",
        "subsystem": "tester"
      }
    }
  ]
}
```

**SDK Code**

```javascript JS
import {
  listOfFiles,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await listOfFiles(
  {},
  { authSchema: uploadcareSimpleAuthSchema }
)

```

```php PHP
<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);

$api = (new Uploadcare\Api($configuration))->file();
$list = $api->listFiles();
foreach ($list->getResults() as $result) {
    echo \sprintf('URL: %s', $result->getUrl());
}
while (($next = $api->nextPage($list)) !== null) {
    foreach ($next->getResults() as $result) {
        echo \sprintf('URL: %s', $result->getUrl());
    }
}

```

```python Python
from pyuploadcare import Uploadcare
uploadcare = Uploadcare(public_key='YOUR_PUBLIC_KEY', secret_key='YOUR_SECRET_KEY')

files = uploadcare.list_files(stored=True, limit=10)
for file in files:
    print(file.info)

```

```ruby Ruby
require 'uploadcare'
Uploadcare.config.public_key = 'YOUR_PUBLIC_KEY'
Uploadcare.config.secret_key = 'YOUR_SECRET_KEY'

list = Uploadcare::FileList.file_list(stored: true, removed: false, limit: 100)
list.each { |file| puts file.inspect }

```

```swift Swift
import Uploadcare

let uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")

let query = PaginationQuery()
  .stored(true)
  .ordering(.dateTimeUploadedDESC)
  .limit(10)
var list = uploadcare.listOfFiles()

try await list.get(withQuery: query)
print(list)

// Next page
if list.next != nil {
  try await list.nextPage()
  print(list)
}

// Previous page
if list.previous != nil {
  try await filesList.previousPage()
  print(list)
}

```

```kotlin Kotlin
import com.uploadcare.android.library.api.UploadcareClient

val uploadcare = UploadcareClient(publicKey = "YOUR_PUBLIC_KEY", secretKey = "YOUR_SECRET_KEY")

val filesQueryBuilder = uploadcare.getFiles()
val files = filesQueryBuilder
    .stored(true)
    .ordering(Order.UPLOAD_TIME_DESC)
    .asList()
Log.d("TAG", files.toString())

```

```go Without App Data
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.uploadcare.com/files/?from=2015-09-10T10%3A00%3A00Z&include=appdata&limit=100&ordering=-datetime_uploaded&removed=true&stored=true"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "application/vnd.uploadcare-v0.7+json")
	req.Header.Add("Authorization", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```java Without App Data
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.uploadcare.com/files/?from=2015-09-10T10%3A00%3A00Z&include=appdata&limit=100&ordering=-datetime_uploaded&removed=true&stored=true")
  .header("Accept", "application/vnd.uploadcare-v0.7+json")
  .header("Authorization", "<apiKey>")
  .asString();
```

```csharp Without App Data
using RestSharp;

var client = new RestClient("https://api.uploadcare.com/files/?from=2015-09-10T10%3A00%3A00Z&include=appdata&limit=100&ordering=-datetime_uploaded&removed=true&stored=true");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/vnd.uploadcare-v0.7+json");
request.AddHeader("Authorization", "<apiKey>");
IRestResponse response = client.Execute(request);
```