دانلودها

فهرست دانلودها

GEThttps://api.parsget.com/api/v1/downloads

OAuth یا Personal API Key

فهرست دانلودهای حساب را از جدیدترین به قدیمی‌ترین دریافت کنید. برای صفحه بعد، مقدار meta.next_cursor را بدون تغییر در پارامتر cursor درخواست بعدی بفرستید.

OAuth Scope: downloads:read

Parameters

Field	Type	Description
`limit`	`integer · query`optional default `50`min 1max 100	تعداد موارد در هر صفحه؛ پیش‌فرض ۵۰ و حداکثر ۱۰۰ مورد.
`cursor`	`string · query`optional	برای صفحه اول نفرستید. برای صفحه بعد، مقدار meta.next_cursor پاسخ قبلی را بدون تغییر بفرستید.
`status`	`string · query`optional `queuedprocessingdownloadingfinalizingcompletedblockedfailedcanceled`	فیلتر بر اساس وضعیت دانلود
`host`	`string · query`optional	برای نمایش دانلودهای یک سرویس، مقدار code آن را از GET /services بفرستید.
`source_hash`	`string · query`optional	هش تورنت (Info Hash) به صورت Hex یا Base32
`client_reference`	`string · query`optional	برای نمایش دانلودهایی که client_reference آن‌ها با این مقدار برابر است.

Response schema

200فهرست دانلودها و اطلاعات صفحه بعد.

Payloadobject[]

Field	Type	Description
`id`	`string`	—
`client_reference`	`string`	برچسب دلخواه برای ارتباط دانلود با داده‌های برنامه شما، مثلاً شناسه قسمت یک مجموعه. چند دانلود می‌توانند برچسب یکسان داشته باشند.
`name`	`string`	—
`status`	`string` `queuedprocessingdownloadingfinalizingcompletedblockedfailedcanceled`	وضعیت دانلود. queued یعنی در صف، processing یعنی در حال بررسی و آماده‌سازی دانلود، downloading یعنی دریافت فایل و finalizing یعنی آماده‌سازی نهایی. completed یعنی تکمیل شده، blocked یعنی نیازمند پرداخت، failed یعنی ناموفق و canceled یعنی لغوشده.
`activity`	`string` `seedingwaiting_for_capacitynull`	پس از تکمیل تورنت، ممکن است ارسال فایل به دیگر کاربران تورنت ادامه داشته باشد. در این حالت، activity برابر seeding و status برابر completed است. وقتی همه اکانت‌های سرویس موقتاً مشغول یا در محدودیت هستند، دانلود با status برابر queued و activity برابر waiting_for_capacity منتظر می‌ماند و با آزاد شدن ظرفیت خودکار ادامه پیدا می‌کند؛ اگر در مهلت تلاش مجدد ظرفیتی آزاد نشود، failed می‌شود.
`source`	`object`
`type`	`string` `urltorrentusenet`	—
`hash`	`string`	هش تورنت (فقط برای دانلودهای تورنت مقدار دارد)
`host`	`string`	کد سرویس دانلود؛ برای اطلاعات سرویس آن را با code در GET /services تطبیق دهید.
`file_id`	`string`	شناسه فایل ایجادشده پس از تکمیل موفق دانلود
`mime_type`	`string`	—
`size_bytes`	`integer`int64	—
`progress`	`object`
`percent`	`number`float min 0max 100	درصد پیشرفت دانلود از ۰ تا ۱۰۰.
`bytes_completed`	`integer`int64 min 0	حجم دریافت‌شده بر حسب بایت.
`speed_bytes_per_second`	`number` min 0	سرعت دریافت بر حسب بایت بر ثانیه؛ اگر مشخص نباشد null است.
`eta_seconds`	`number` min 0	زمان تخمینی باقی‌مانده بر حسب ثانیه؛ اگر مشخص نباشد null است.
`can_cancel`	`boolean`	اگر true باشد، می‌توانید دانلود را لغو کنید. دکمه لغو را بر اساس این مقدار نمایش دهید.
`can_retry`	`boolean`	اگر true باشد، می‌توانید دانلود را دوباره شروع کنید. دکمه تلاش مجدد را بر اساس این مقدار نمایش دهید.
`error`	`object \| null`
`code`	`string` `source_unavailabledownload_expiredquota_exceededdownload_failed`	—
`message`	`string`	—
`created_at`	`string`date-time	—
`updated_at`	`string`date-time	—
`completed_at`	`string`date-time	—
`attempt`	`integer` min 1	شماره تلاش دانلود، از ۱. با شروع موفق یک تلاش جدید از طریق endpoint retry افزایش می‌یابد.

Metaobject

پاسخ‌های خطاساختار استاندارد error

Example

{
  "data": [
    {
      "id": "01M1BDA500B4A6D9K3N5R7T8VC",
      "client_reference": "episode-42",
      "name": "big-buck-bunny.mp4",
      "status": "downloading",
      "activity": null,
      "source": {
        "type": "url",
        "hash": null
      },
      "host": "youtube",
      "file_id": null,
      "mime_type": "video/mp4",
      "size_bytes": 1073741824,
      "progress": {
        "percent": 42.5,
        "bytes_completed": 456130560,
        "speed_bytes_per_second": 12582912,
        "eta_seconds": 47
      },
      "can_cancel": true,
      "can_retry": false,
      "error": null,
      "created_at": "2026-08-31T08:00:00.000000Z",
      "updated_at": "2026-08-31T08:01:20.000000Z",
      "completed_at": null,
      "attempt": 1
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6IjAxTTFCREE1MDBCNEE2RDlLM041UjdUOFZDIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
    "has_more": true
  }
}