- started: The first request to the tracker must include the event key with the started value.
- stopped: Must be sent to the tracker if the client is shutting down gracefully.
- completed: Must be sent to the tracker when the download completes. However, must not be sent if the download was already 100% complete when the client started. Presumably, this is to allow the tracker to increment the "completed downloads" metric based soley on this event.
The tracker responds with "text/plain" document consisting of a bencoded dictionary with the following keys:
- failure reason: If present, then no other keys may be present. The value is a human-readable error message as to why the request failed (string).
- interval: Interval in seconds that the client should wait between sending regular requests to the tracker
- complete: number of peers with the entire file, i.e. seeders (integer)
- incomplete: number of non-seeder peers, aka "leechers" (integer)
-
peers: The value is a list of dictionaries, each with the following keys:
- peer id: peer's self-selected ID, as described above for the tracker request (string)
- ip: peer's IP address (either IPv6 or IPv4) or DNS name (string)
- port: peer's port number (integer)
As mentioned above, the list of peers is length 50 by default. If there are fewer peers in the torrent, then the list will be smaller. Otherwise, the tracker randomly selects peers to include in the response. The tracker may choose to implement a more intelligent mechanism for peer selection when responding to a request. For instance, reporting seeds to other seeders could be avoided.
Clients may send a request to the tracker more often than the specified interval, if an event occurs (i.e. stopped or completed) or if the client needs to learn about more peers. However, it is considered bad practice to "hammer" on a tracker to get multiple peers. If a client wants a large peer list in the response, then it should specify the numwant parameter.
Tracker 'scrape' Convention
By convention most trackers support another form of request, which queries the state of a given torrent (or all torrents) that the tracker is managing. This is referred to as the "scrape page" because it automates the otherwise tedious process of "screen scraping" the tracker's stats page.
The scrape URL is also a HTTP GET method, similar to the one described above. However the base URL is different. To derive the scrape URL use the following steps: Begin with the announce URL. Find the last '/' in it. If the text immediately following that '/' isn't 'announce' it will be taken as a sign that that tracker doesn't support the scrape convention. If it does, substitute 'scrape' for 'announce' to find the scrape page.
Examples: (announce URL -> scrape URL)
