> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sanitizeemail.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Uploaded Files
> Retrieve a paginated list of uploaded files with optional filtering by file tag
This endpoint retrieves a paginated list of uploaded files with optional filtering capabilities. You can filter by file purpose and control pagination through query parameters.
## Query Parameters
All parameters are optional and can be combined:
* **file\_tag**: Filter files by their processing purpose (`clean`, `validate`, `analyze`)
* **size**: Number of files to return per page (1-100, default: 10)
* **page**: Page number for pagination (starts from 1)
## How it Works
Choose a file\_tag to filter by processing purpose, or omit to see all files
Set size and page parameters to control how many files are returned and
which page to view
Send a GET request with your chosen parameters
Use the next/previous URLs in the response for easy pagination
## Response Structure
The response follows a standard pagination format:
### Pagination Meta
* **count**: Total number of files matching your query
* **next**: URL for the next page (null if on last page)
* **previous**: URL for the previous page (null if on first page)
### File Results
Each file in the results array contains the same detailed information as the [individual file endpoint](/api-reference/endpoint/view_file).
## Example Usage
Get all files with default pagination: `bash GET /v1/api/filesupload/ `
Get only validation files: `bash GET
/v1/api/filesupload/?file_tag=validate `
Get 6 files per page, starting from page 2: `bash GET
/v1/api/filesupload/?size=6&page=2 `
Get analyze files with custom pagination: `bash GET
/v1/api/filesupload/?file_tag=analyze&size=6&page=2 `
## File Tag Filtering
Use the `file_tag` parameter to filter files by their processing purpose:
**file\_tag=clean** Files uploaded for email cleaning and removal of invalid
addresses
**file\_tag=validate** Files uploaded for email validation and deliverability
checking
**file\_tag=analyze** Files uploaded for detailed email analysis and insights
## Response Example
```json theme={null}
{
"count": 7,
"next": "https://base.sanitizeemail.com/v1/api/filesupload/?file_tag=validate&page=3&size=6",
"previous": "https://base.sanitizeemail.com/v1/api/filesupload/?file_tag=validate&page=1&size=6",
"results": [
{
"id": 745,
"name": "Customer Email List",
"file_name": "customers.csv",
"file_size": "328",
"status": "validated",
"user": {
"id": 100,
"username": "asim",
"email": "cool@gmail.com"
},
"file": "https://s3.us-east-1.amazonaws.com/sanitizeemail/email_validation_files/customers_uJWaJWs.csv",
"file_tag": "validate",
"total_email": 8,
"billable_email": 4,
"duplicate_email": 4,
"dropped_email": 0,
"clean_email_count": 4,
"bounced_email": 0,
"bounce_rate": 0,
"created_date": "2025-07-13T10:35:04.351377+05:45",
"is_file_organised": false,
"progress_percentage": 100,
"updated_date": "2025-07-13T10:35:07.923638+05:45",
"valid_emails_count": 4,
"invalid_emails_count": 0,
"clean_email_id": null,
"validate_email_id": 23990312
}
]
}
```
## Use Cases
Browse and manage all your uploaded files in one place
Check the processing status of multiple files at once
View files by their processing purpose (clean, validate, analyze)
Prepare for batch operations by getting file IDs and URLs
**Pagination**: The API uses cursor-based pagination. Use the `next` and
`previous` URLs provided in the response for seamless navigation between
pages.
**Performance**: For large file collections, use filtering and pagination to
improve response times and reduce bandwidth usage.
## OpenAPI
````yaml GET /v1/api/filesupload/
openapi: 3.1.0
info:
title: Sanitize-Email API (v1)
description: Welcome to the Sanitize-Email API Documentation
license:
name: Proprietary License
version: 1.0.0
servers:
- url: https://base.sanitizeemail.com
security:
- apiKeyAuth: []
paths:
/v1/api/filesupload/:
get:
tags:
- File Upload
summary: List Uploaded Files
description: >-
Retrieve a paginated list of uploaded files with optional filtering by
file tag
parameters:
- $ref: '#/components/parameters/FileTag'
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: List of files retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FileListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
components:
parameters:
FileTag:
name: file_tag
in: query
required: false
schema:
type: string
enum:
- clean
- validate
- analyze
description: Filter files by their processing purpose/tag
example: validate
Size:
name: size
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
description: Number of results to return per page.
example: 20
Page:
name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
description: Page number for pagination.
example: 1
schemas:
FileListResponse:
type: object
properties:
count:
type: integer
description: Total number of files matching the query
next:
type: string
format: uri
nullable: true
description: URL for the next page of results
previous:
type: string
format: uri
nullable: true
description: URL for the previous page of results
results:
type: array
items:
$ref: '#/components/schemas/FileDetailsResponse'
description: Array of file objects for the current page
FileDetailsResponse:
type: object
properties:
id:
type: integer
description: Unique identifier of the file
name:
type: string
description: Display name of the file
file_name:
type: string
description: Original filename
file_size:
type: string
description: File size in bytes
status:
type: string
enum:
- pending
- processing
- validated
- cleaned
- failed
description: Current processing status of the file
user:
$ref: '#/components/schemas/User'
file:
type: string
format: uri
description: URL to access the uploaded file
file_tag:
type: string
enum:
- clean
- validate
- analyze
description: Tag associated with the file processing type
total_email:
type: integer
description: Total number of emails found in the file
billable_email:
type: integer
description: Number of emails that count towards billing
duplicate_email:
type: integer
description: Number of duplicate emails found
dropped_email:
type: integer
description: Number of emails that were dropped during processing
clean_email_count:
type: integer
description: Number of clean/valid emails
bounced_email:
type: integer
description: Number of emails that bounced
bounce_rate:
type: number
format: float
description: Bounce rate as a decimal (0.0 to 1.0)
created_date:
type: string
format: date-time
description: Date and time when the file was uploaded
is_file_organised:
type: boolean
description: Whether the file was uploaded as organized (with headers)
progress_percentage:
type: integer
minimum: 0
maximum: 100
description: Processing progress percentage
updated_date:
type: string
format: date-time
description: Date and time when the file was last updated
valid_emails_count:
type: integer
description: Number of valid emails
invalid_emails_count:
type: integer
description: Number of invalid emails
clean_email_id:
type: integer
nullable: true
description: ID of the clean email list (if cleaning was performed)
validate_email_id:
type: integer
nullable: true
description: ID of the validation job (if validation was performed)
Error:
required:
- error
- message
type: object
properties:
error:
type: integer
format: int32
message:
type: string
User:
type: object
properties:
id:
type: integer
description: User ID
username:
type: string
description: Username
email:
type: string
format: email
description: User email address
responses:
Unauthorized:
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: API key for authentication
````