Title:Tracker Protocol Extension: Scrape
Version: 879de8e9c290a33be874b567cd1c8ec4df0900f4
Last-Modified:Mon Sep 19 09:46:58 2016 -0700
Author: Jimmy Zelinskie <>
Status: Draft
Type:Standards Track


The original BitTorrent Protocol Specification [1] defines one exchange between a client and a tracker referred to as an announce. In order to build responsive user interfaces, clients desired an additional way to query metadata about swarms in bulk. The exchange that fetches this metadata for the clients is referred to as a scrape. It should be noted that scrape exchanges have no effect on a peer's participation in a swarm.


As the UDP Tracker Protocol Specification [2] already defines the implementation of scrape using the UDP protocol, the following will document the implementation for the HTTP protocol.

Scrape Request

In order for a client to create a scrape request, it must first determine the HTTP URL for the scrape endpoint. This is done by locating the string announce in the path section [3] of the announce URL and replacing it with the string scrape. Performing a scrape request to URLs that are not determined by this method are outside of the scope of this specification.

A scrape request contains no HTTP body, but instead uses HTTP query parameters [3] to encode its key-value pairs. There is only one key, the info_hash key specified in BEP 003 [1]. This key can be appended multiple times with different values for collecting data about multiple swarms in one request.

Scrape Response

The response to a successful request is a bencoded dictionary containing one key-value pair: the key files with the value being a dictionary of the 20-byte string representation of an infohash paired with a dictionary of swarm metadata. The fields found in the swarm metadata dictionary are as follows:

The number of active peers that have completed downloading.
The number of active peers that have not completed downloading.
The number of peers that have ever completed downloading.

The response to an unsuccessful request is a bencoded dictionary with the key failure_reason and a string value as described in BEP 003 [1].






Response (JSON encoded for readability):

  'files': {
    'xxxxxxxxxxxxxxxxxxxx': {'complete': 11, 'downloaded': 13772, 'incomplete': 19},
    'yyyyyyyyyyyyyyyyyyyy': {'complete': 21, 'downloaded': 206, 'incomplete': 20}


[1](1, 2, 3) BEP 0003. The BitTorrent Protocol Specification. (
[2]BEP 0015. UDP Tracker Protocol for BitTorrent. (
[3](1, 2) URL Syntax. Wikipedia. (