Onionoo

The Tor network status protocol providing the
data for other applications and websites.



The Tor network status protocol

Onionoo is a web-based protocol to learn about currently running Tor relays and bridges. Onionoo itself was not designed as a service for human beings—at least not directly. Onionoo provides the data for other applications and websites which in turn present Tor network status information to humans.

Tell me more!


Table of contents

GeneralProtocol versionsMethodsResponsesSummary documentsDetails documentsHistory objectsBandwidth documentsWeights documentsClients documentsUptime documentsExample usage

The Tor network status protocol #


General #

The Onionoo service is designed as a RESTful web service. Onionoo clients send HTTP GET requests to the Onionoo server which responds with JSON-formatted replies. Onionoo clients and their developers should follow a few rules:


Compression

Clients should include an "Accept-Encoding: gzip" header in their requests and handle gzip-compressed responses. Only requests starting at a certain size will be compressed by the server.


Caching

Clients should make use of the "Last-Modified"header of responses and include that timestamp in a"If-Modified-Since" header of subsequent requests.


Response codes

Clients should handle response codes by distinguishing between client and server errors, and if there's a problem, informing their users about the kind of problem. The following response codes are used:


Protocol versions #

There are plenty of reasons why we may have to change the protocol described here. Clients should be able to handle all valid JSON responses, ignoring unknown fields and not breaking horribly in case of missing fields. Protocol changes will be announced here by writing deprecated API parts with the label deprecated and new parts with the label new. Deprecated parts will be removed one month after their announcement.

All responses contain a "version" string that indicates whether clients can parse the document or not. Version strings consist of a major and a minor version number. The major version number is raised when previously required fields are dropped or turned into optional fields, when request parameters or response documents are removed, or when there are structural changes. The minor version number is raised when new fields, request parameters, or response documents are added or optional fields are dropped. If clients support the same major version given in a response but only a lower minor version, they should be able to parse the document but may not understand all fields. If clients support a lower major version, they should not attempt to parse a document, because there may be backward-incompatible changes.

Responses may also contain the optional"next_major_version_scheduled" field that announces when the next major version is scheduled to be deployed. Clients should inform their users that they should upgrade to the next major protocol version before the provided date.

The following versions have been used in the past six months or are scheduled to be deployed in the next months:


Methods #

The following methods each return a single document containing zero or more objects of relays and/or bridges. By default, all relays and bridges are included that have been running in the past week.

MethodURLDescription
GEThttps://onionoo.torproject.org/summaryreturns a summary document
GEThttps://onionoo.torproject.org/detailsreturns a details document
GEThttps://onionoo.torproject.org/bandwidthreturns a bandwidth document
GEThttps://onionoo.torproject.org/weightsreturns a weights document
GEThttps://onionoo.torproject.org/clientsreturns a clients document
GEThttps://onionoo.torproject.org/uptimereturns an uptime document

Parameters

Each of the methods can be parameterized to select only a subset of relay and/or bridge documents that are currently running or that have been running in the past week. (The fingerprint parameter is special here, because it allows selecting a specific relay or bridge, regardless of whether it has been running in the past week.) If multiple parameters are specified, they are combined using a logical AND operation, meaning that only the intersection of relays and bridges matching all parameters is returned. If the same parameter is specified more than once, only the first parameter value is considered.

Response documents can be reduced in size by requesting only a subset of contained fields.

Relay and/or bridge documents in the response can be ordered and limited by providing further parameters. If the same parameter is specified more than once, only the first parameter value is considered.


Responses #

Responses all have the same structure, regardless of requested method and provided parameters. Responses contain the following fields:


Summary documents #example request

Summary documents contain short summaries of relays with nicknames, fingerprints, IP addresses, and running information as well as bridges with hashed fingerprints and running information.

Relay summary objects

Relay summary objects contain the following key-value pairs:

Bridge summary objects

Bridge summary objects contain the following key-value pairs:


Details documents #example request

Details documents are based on network statuses published by the Tor directories, server descriptors published by relays and bridges, and data published by Tor network services TorDNSEL and BridgeDB. Details documents use the most recently published data from these sources, which may lead to contradictions between fields based on different sources in rare edge cases.

Relay details objects

Relay details objects contain the following key-value pairs:

Bridge details objects

Bridge details objects contain the following key-value pairs:


History objects #

History objects are no documents by themselves, but are contained in subsequent documents.

Graph history objects

Graph history objects contain the following fields:


Bandwidth documents #example request

Bandwidth documents contain aggregate statistics of a relay's or bridge's consumed bandwidth for different time intervals. Bandwidth documents are only updated when a relay or bridge publishes a new server descriptor, which may take up to 18 hours during normal operation.

Relay bandwidth objects

Relay bandwidth objects contain the following key-value pairs:

Bridge bandwidth objects

Bridge bandwidth objects contain the following key-value pairs:


Weights documents #example request

Weights documents contain aggregate statistics of a relay's probability to be selected by clients for building paths. Weights documents contain different time intervals and are available for relays only.

Relay weights objects

Relay weights objects contain the following key-value pairs:


Clients documents #example request

Clients documents contain estimates of the average number of clients connecting to a bridge every day. There are no clients documents available for relays, just for bridges. Clients documents contain different time intervals and are available for bridges only.

Bridge clients objects

Bridge clients objects contain the following key-value pairs:


Uptime documents #example request

Uptime documents contain fractional uptimes of relays and bridges. Uptime documents contain different time intervals and are available for relays and bridges.

Relay uptime objects

Relay uptime objects contain the following key-value pairs:

Bridge uptime objects

Bridge uptime objects contain the following key-value pairs:


Example usage #

The following examples illustrate how to build requests for some trivial and some more complex use cases. While Onionoo is designed mainly for developers and not end users, there may be cases when it's easier to quickly write a specific query Onionoo rather than to find an Onionoo client that provides the desired information.

/summary?limit=4(view result)

This first query returns the first four summary documents that Onionoo can find. The limit parameter should always be used while developing new queries to avoid downloading huge responses.

/summary?limit=4&search=moria(view result)

The second query restricts results to relays and bridges containing the string "moria" in one of a few searched fields.

/details?limit=4&search=moria(view result)

The third query switches from the short summary documents to the longer details documents containing, well, more details.

/details?limit=4&search=moria&fields=nickname(view result)

The fourth query adds the fields parameter which removes all fields except the specified ones from the result. This parameter is only implemented for details documents.

/details?limit=4&search=moria&fields=nickname&order=-consensus_weight(view result)

The fifth query sorts results by relay consensus weight from largest to smallest.

Obviously, this query can be made even more complex by adding more parameters, and in some cases this is necessary and useful. Please refer to the protocol specification for details.

© 2017 The Tor Project

Data on this site is freely available under a : To the extent possible under law, the Tor Project has waived all copyright and related or neighboring rights in the data. "Tor" and the "Onion Logo" are of The Tor Project, Inc.