Skip to main content
GET
/
api
/
downloads
List Downloads
curl --request GET \
  --url https://api.example.com/api/downloads
{
  "id": "<string>",
  "url": "<string>",
  "title": "<string>",
  "thumbnail": "<string>",
  "status": "<string>",
  "progress": 123,
  "speed": "<string>",
  "eta": "<string>",
  "filesize": 123,
  "downloaded_bytes": 123,
  "format_note": "<string>",
  "is_playlist": true,
  "playlist_index": 123,
  "playlist_total": 123,
  "filename": "<string>",
  "quality": "<string>",
  "download_type": "<string>",
  "error_message": "<string>",
  "created_at": "<string>",
  "completed_at": {}
}

​
Response

Returns an array of download task objects.
​
id
string
Unique identifier for the download task
​
url
string
The original URL that was requested for download
​
title
string
The title of the video/audio (extracted after download starts)
​
thumbnail
string
URL or path to the thumbnail image. May be a local API path (/api/thumbnails/{id}) or an external URL
​
status
string
Current status of the download. Possible values:
  • "pending" - Queued, not started yet
  • "downloading" - Currently downloading
  • "processing" - Download complete, processing/merging streams
  • "completed" - Fully complete and ready for retrieval
  • "error" - Download failed
  • "cancelled" - User cancelled the download
​
progress
number
Download progress percentage (0-100)
​
speed
string
Current download speed (e.g., “5.2 MB/s” or “850 KB/s”)
​
eta
string
Estimated time remaining (e.g., ”45s”)
​
filesize
integer
Total file size in bytes
​
downloaded_bytes
integer
Number of bytes downloaded so far
​
format_note
string
Actual quality of the downloaded file (e.g., “1080p”, “128kbps”)
​
is_playlist
boolean
Whether the URL is a playlist
​
playlist_index
integer
Current video index in playlist (if applicable)
​
playlist_total
integer
Total number of videos in playlist (if applicable)
​
filename
string
Name of the downloaded file on disk
​
quality
string
The requested quality setting (e.g., “720p”)
​
download_type
string
Type of download: "video" or "audio"
​
error_message
string
Error details if status is "error"
​
created_at
string
ISO 8601 timestamp when the download was initiated
​
completed_at
string | null
ISO 8601 timestamp when the download completed, or null if not yet completed

​
Example Request

cURL
curl https://your-api.com/api/downloads

​
Example Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "title": "Rick Astley - Never Gonna Give You Up",
    "thumbnail": "/api/thumbnails/550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "progress": 100,
    "speed": "",
    "eta": "",
    "filesize": 52428800,
    "downloaded_bytes": 52428800,
    "format_note": "1080p",
    "is_playlist": false,
    "playlist_index": 0,
    "playlist_total": 1,
    "filename": "Rick Astley - Never Gonna Give You Up__550e8400-e29b-41d4-a716-446655440000.mp4",
    "quality": "1080p",
    "download_type": "video",
    "error_message": "",
    "created_at": "2026-03-04T10:30:00.000Z",
    "completed_at": "2026-03-04T10:35:22.000Z"
  },
  {
    "id": "660f9500-f39c-52e5-b827-557766550111",
    "url": "https://www.youtube.com/watch?v=example123",
    "title": "Example Video",
    "thumbnail": "https://i.ytimg.com/vi/example123/hqdefault.jpg",
    "status": "downloading",
    "progress": 45.5,
    "speed": "3.2 MB/s",
    "eta": "120s",
    "filesize": 104857600,
    "downloaded_bytes": 47710208,
    "format_note": "720p",
    "is_playlist": false,
    "playlist_index": 0,
    "playlist_total": 1,
    "filename": "",
    "quality": "720p",
    "download_type": "video",
    "error_message": "",
    "created_at": "2026-03-04T10:40:00.000Z",
    "completed_at": null
  }
]

​
Use Cases

  • Progress Monitoring: Poll this endpoint to display real-time download progress in your UI
  • Download History: View all past and current downloads
  • Status Checking: Determine which downloads are complete and ready for retrieval