Home > Specs > BitTorrent > Trackers
HTTP Trackers

An HTTP tracker uses a regular TCP connection followed by a standard GET request.  The parameters for the announce are sent in the URL, in the query parameters section.  The server will respond with a regular HTTP response, with a BEncoded map in the response body.


Here is an example request:


Here are the parameters used in the query:

info_hash
The info hash of the torrent being announced.

peer_id
This is the local peer ID for this torrent, which is also used for peer connection handshakes.

port
This is the local incoming connection port.

uploaded
If this is a STARTED event, this is zero, otherwise it's the number of bytes that have been uploaded in this torrent since the STARTED event.

downloaded
If this is a STARTED event, this is zero, otherwise it's the number of bytes that have been downloaded in this torrent since the STARTED event.

left
This is the total byte size of the torrent minus the bytes that have been downloaded.

corrupt
This is supposed to be how many bad bytes that failed hash-check have been downloaded.  It is never used.  Leave it as zero, or omit this parameter entirely.

key
If we are announcing a STARTED event, this should be a randomly generated string.  Otherwise, the string generated for the earlier STARTED event should be used.

event
Use started if we are announcing a STARTED event, which is always the first event we announce, even if the torrent is complete.  Use completed to announce that a torrent that was already started has now completed.  Use stopped to announce that the torrent is no longer running.  Do not include an event parameter if none of the other codes apply and the announcement is just being refreshed.

numwant
This is the number of peers that is desired in the response.  Set it to 100 unless we are making a STOPPED announcement, in which case it should be zero.  The tracker may send more or less than this number.

compact
Always set this to 1.  Non-compact responses are much longer because they represent peer IPs as characters.  Non-compact responses may not be supported by some trackers at all.

no_peer_id
Always set this to 1.  If the tracker does not support compact responses, this will omit peer IDs from the response.  Peer IDs are not useful in this context.


The tracker will reply with a conventional HTTP response of code 200 OK.  The useful data is contained in the response body, in the form of a BEncoded map with the following keys:

complete
The number of peers the tracker knows about for this torrent that are complete.

incomplete
The number of peers the tracker knows about for this torrent that are incomplete.

interval
How many seconds to wait before refreshing the announcement.

peers
This key will either contain a compact response in the form of a string, or a non-compact response in the form of a list.  Compact responses are a series of 4-byte IP + 2-byte port pairs.  Non-compact responses are lists of maps, with two keys, ip that contains a text representation of the IP and port which contains an integer.

peers6 or peers_ipv6
This key will either contain a compact response in the form of a string, or a non-compact response in the form of a list.  Compact responses are a series of 16-byte IP + 2-byte port pairs.  Non-compact responses are lists of maps, with two keys, ip that contains a text representation of the IP and port which contains an integer.