How to Pause or Unpause aria2 Downloads via RPC?

Managing downloads remotely can significantly streamline your server administration and automation workflows. This article provides a straightforward guide on how to pause and unpause active downloads using the aria2 Remote Procedure Call (RPC) API. You will learn the specific API methods required, the structure of the JSON-RPC requests, and how to execute these commands using common tools like curl.

Understanding the aria2 RPC Interface

The aria2 download utility features a powerful RPC interface that accepts JSON-RPC 2.0 requests over HTTP or WebSockets. To control a specific download, you must interact with it using its GID (Download Global Identifier), which is a unique 16-character hex string assigned by aria2 to every download task.

Pausing an Active Download

To pause a download that is currently active or waiting in the queue, you use the aria2.pause method. If you want to force the download to pause immediately without waiting for handshake processes to complete, you can use aria2.forcePause.

JSON-RPC Request Payload

{
  "jsonrpc": "2.0",
  "id": "remote-control",
  "method": "aria2.pause",
  "params": ["token:YOUR_SECRET_TOKEN", "GID_OF_DOWNLOAD"]
}

Sending the Request with cURL

curl -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"remote-control","method":"aria2.pause","params":["token:YOUR_SECRET_TOKEN","GID_OF_DOWNLOAD"]}' \
http://localhost:6800/jsonrpc

If successful, the server will return a response containing the GID of the paused download.

Unpausing a Download

To resume a download that has been paused, the RPC API provides the aria2.unpause method. This moves the status of the download from “paused” back to “waiting” or “active”.

JSON-RPC Request Payload

{
  "jsonrpc": "2.0",
  "id": "remote-control",
  "method": "aria2.unpause",
  "params": ["token:YOUR_SECRET_TOKEN", "GID_OF_DOWNLOAD"]
}

Sending the Request with cURL

curl -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"remote-control","method":"aria2.unpause","params":["token:YOUR_SECRET_TOKEN","GID_OF_DOWNLOAD"]}' \
http://localhost:6800/jsonrpc

Global Control Options

If you need to halt or resume all tasks simultaneously rather than targeting a single GID, aria2 offers global alternative methods that do not require a GID parameter: