Skip to main content

torrents.list

Lists torrents in Porla. This method uses pagination in order to support cases where large amounts of torrents are in the session.

Request

{
// A zero based index of the page to fetch. Defaults to 0.
"page": 0,

// Sets how many torrents per page to return. Defaults to 50.
"page_size": 100,

// Which field to order torrents by. Supports the following fields,
// - "name"
// - "queue_position"
// - "size"
// Defaults to "queue_position".
"order_by": "name",

// Sets the order_by direction - either "asc" for ascending order, or "desc"
// for descending order. Defaults to "asc".
"order_by_dir": "asc"
}

Response

{
// The page of torrents returned.
"page": 0,

// The page size of the result. The number of torrents returned is equal to,
// or less, than this.
"page_size": 50,

// The torrents in this page.
"torrents": [
{
// the total rates for all peers for this torrent. These will usually
// have better precision than summing the rates from all peers. The rates
// are given as the number of bytes per second.
"download_rate": 788,
"upload_rate": 123,

// reflects several of the torrent's flags
"flags": 129,

// the torrents info hash
"info_hash": [ "", null ],

// the number of seeds in our peer list and the total number of peers
// (including seeds). We are not necessarily connected to all the peers
// in our peer list. This is the number of peers we know of in total,
// including banned peers and peers that we have failed to connect to.
"list_peers": 87,
"list_seeds": 89,

// the name of the torrent. Typically this is derived from the
// .torrent file. In case the torrent was started without metadata,
// and hasn't completely received it yet, it returns the name given
// to it when added to the session.
"name": "ubuntu",

// the number of peers this torrent currently is connected to. Peer
// connections that are in the half-open state (is attempting to connect)
// or are queued for later connection attempt do not count. Although they
// are visible in the peer list
"num_peers": 898,

// the number of peers that are seeding that this client is
// currently connected to.
"num_seeds": 76,

// a value in the range [0, 1], that represents the progress of the
// torrent's current task. It may be checking files or downloading.
"progress": 0.54487,

// the position this torrent has in the download queue. If the torrent is
// a seed or finished, this is -1.
"queue_position": 9,

// the path to the directory where this torrent's files are stored.
"save_path": "/dl/my-stuff",

// the total number of bytes the torrent-file represents. Note that this
// is the number of pieces times the piece size (modulo the last piece
// possibly being smaller). With pad files, the total size will be larger
// than the sum of all (regular) file sizes.
"size": 87677,

// the total number of bytes to download for this torrent. This may be
// less than the size of the torrent in case there are pad files. This
// number only counts bytes that will actually be requested from peers.
"total": 887,

// the total number of bytes of the file(s) that we have. All this does
// not necessarily has to be downloaded during this session (that's
// ``total_payload_download``).
"total_done": 766,
}
],

// The total amount of torrents in the session. This can be used to determine
// the amount of pages, etc.
"torrents_total": 45007
}