Onionoo
  • General
  • Protocol versions
  • Methods
  • Responses
  • Summary documents
  • Details documents
  • History objects
  • Bandwidth documents
  • Weights documents
  • Clients documents
  • Uptime documents
  • Example usage
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

General Protocol versions Methods Responses Summary documents Details documents History objects Bandwidth documents Weights documents Clients documents Uptime documents Example 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:

  • 200 OK

    The request was processed successfully.

  • 304 Not Modified

    Server data has not changed since the "If-Modified-Since" header included in the request.

  • 400 Bad Request

    The request for a known resource could not be processed because of bad syntax. This is most likely a client problem.

  • 404 Not Available

    The request could not be processed because the requested resource could not be found. This is most likely a client problem.

  • 500 Internal Server Error

    There is an unspecific problem with the server which the service operator may not yet be aware of. Please check if there's already a bug report for this problem, and if not, file one.

  • 503 Service Unavailable

    The server is temporarily down for maintenance, or there is a temporary problem with the server that the service operator is already aware of. Only file a bug report if this problem persists.


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:

  • 1.0: First assigned version number on August 31, 2014.
  • 1.1: Added optional "next_major_version_scheduled" field on September 16, 2014.
  • 1.2: Added qualified search terms to "search" parameter on October 17, 2014.
  • 2.0: Extended search parameter to base64-encoded fingerprints on November 15, 2014.
  • 2.1: Removed optional "advertised_bandwidth_fraction" field from details documents and optional "advertised_bandwidth" and "advertised_bandwidth_fraction" fields from weights documents on November 16, 2014.
  • 2.2: Removed optional "pool_assignment" field and added "transports" field to bridge details documents on December 8, 2014.
  • 2.3: Added optional "flags" field to uptime documents on March 22, 2015.
  • 2.4: Added optional "effective_family" field to details documents on July 3, 2015.
  • 2.5: Added optional "measured" field to details documents on August 13, 2015.
  • 2.6: Added optional "alleged_family" and "indirect_family" fields and deprecated optional "family" field in details documents on August 25, 2015.
  • 3.0: Extended search parameter to match any 4 hex characters of a space-separated fingerprint on November 15, 2015.
  • 3.1: Removed optional "family" field on January 18, 2016.
  • 3.2: Extended order parameter to "first_seen" and added response meta data fields "relays_skipped", "relays_truncated", "bridges_skipped", and "bridges_truncated" on January 27, 2017.
  • 4.0: Extended search parameter to not require leading or enclosing square brackets around IPv6 addresses anymore on February 28, 2017.

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.

Method URL Description
GET https://onionoo.torproject.org/summary returns a summary document
GET https://onionoo.torproject.org/details returns a details document
GET https://onionoo.torproject.org/bandwidth returns a bandwidth document
GET https://onionoo.torproject.org/weights returns a weights document
GET https://onionoo.torproject.org/clients returns a clients document
GET https://onionoo.torproject.org/uptime returns 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.

  • type

    Return only relay (parameter value relay) or only bridge documents (parameter value bridge). Parameter values are case-insensitive.

  • running

    Return only running (parameter value true) or only non-running relays and/or bridges (paramter value false). Parameter values are case-insensitive.

  • search

    Return only (1) relays with the parameter value matching (part of a) nickname, (possibly $-prefixed) beginning of a hex-encoded fingerprint, any 4 hex characters of a space-separated fingerprint, beginning of a base64-encoded fingerprint without trailing equal signs, or beginning of an IP address (possibly enclosed in square brackets in case of IPv6), (2) bridges with (part of a) nickname or (possibly $-prefixed) beginning of a hashed hex-encoded fingerprint, and (3) relays and/or bridges matching a given qualified search term. Searches by relay IP address include all known addresses used for onion routing and for exiting to the Internet. Searches for beginnings of IP addresses are performed on textual representations of canonical IP address forms, so that searches using CIDR notation or non-canonical forms will return empty results. Searches are case-insensitive, except for base64-encoded fingerprints. If multiple search terms are given, separated by spaces, the intersection of all relays and bridges matching all search terms will be returned. Complete hex-encoded fingerprints should always be hashed using SHA-1, regardless of searching for a relay or a bridge, in order to not accidentally leak non-hashed bridge fingerprints in the URL. Qualified search terms have the form "key:value" (without double quotes) with "key" being one of the parameters listed here except for "search", "fingerprint", "order", "limit", "offset", and "fields", and "value" being the string that will internally be passed to that parameter.

  • lookup

    Return only the relay with the parameter value matching the fingerprint or the bridge with the parameter value matching the hashed fingerprint. Fingerprints should always be hashed using SHA-1, regardless of looking up a relay or a bridge, in order to not accidentally leak non-hashed bridge fingerprints in the URL. Lookups only work for full fingerprints or hashed fingerprints consisting of 40 hex characters. Lookups are case-insensitive.

  • fingerprint

    Return only the relay with the parameter value matching the fingerprint or the bridge with the parameter value matching the hashed fingerprint. Fingerprints must consist of 40 hex characters, case does not matter. This parameter is quite similar to the lookup parameter with two exceptions: (1) the provided relay fingerprint or hashed bridge fingerprint must not be hashed (again) using SHA-1; (2) the response will contain any matching relay or bridge regardless of whether they have been running in the past week.

  • country

    Return only relays which are located in the given country as identified by a two-letter country code. Filtering by country code is case-insensitive.

  • as

    Return only relays which are located in the given autonomous system (AS) as identified by the AS number (with or without preceding "AS" part). Filtering by AS number is case-insensitive.

  • flag

    Return only relays which have the given relay flag assigned by the directory authorities. Note that if the flag parameter is specified more than once, only the first parameter value will be considered. Filtering by flag is case-insensitive.

  • first_seen_days

    Return only relays or bridges which have first been seen during the given range of days ago. A parameter value "x-y" with x <= y returns relays or bridges that have first been seen at least x and at most y days ago. Accepted short forms are "x", "x-", and "-y" which are interpreted as "x-x", "x-infinity", and "0-y".

  • last_seen_days

    Return only relays or bridges which have last been seen during the given range of days ago. A parameter value "x-y" with x <= y returns relays or bridges that have last been seen at least x and at most y days ago. Accepted short forms are "x", "x-", and "-y" which are interpreted as "x-x", "x-infinity", and "0-y". Note that relays and bridges that haven't been running in the past week are not included in results, so that setting x to 8 or higher will lead to an empty result set.

  • contact

    Return only relays with the parameter value matching (part of) the contact line. If the parameter value contains spaces, only relays are returned which contain all space-separated parts in their contact line. Only printable ASCII characters are permitted in the parameter value, some of which need to be percent-encoded (# as %23, % as %25, & as %26, + as %2B, and / as %2F). Comparisons are case-insensitive.

  • family

    Return only the relay whose fingerprint matches the parameter value and all relays that this relay has listed in its family by fingerprint and that in turn have listed this relay in their family by fingerprint. If relays have listed other relays in their family by nickname, those family relationships will not be considered, regardless of whether they have the Named flag or not. The provided relay fingerprint must consist of 40 hex characters where case does not matter, and it must not be hashed using SHA-1. Bridges are not contained in the result, regardless of whether they define a family.

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

  • fields

    Comma-separated list of fields that will be included in the result. So far, only top-level fields in relay or bridge objects of details documents can be specified, e.g., nickname,hashed_fingerprint. If the fields parameter is provided, all other fields which are not contained in the provided list will be removed from the result. Field names are case-insensitive.

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.

  • order

    Re-order results by a comma-separated list of fields in ascending or descending order. Results are first ordered by the first list element, then by the second, and so on. Possible fields for ordering are: consensus_weight and first_seen. Field names are case-insensitive. Ascending order is the default; descending order is selected by prepending fields with a minus sign (-). Field names can be listed at most once in either ascending or descending order. Relays or bridges which don't have any value for a field to be ordered by are always appended to the end, regardless or sorting order. The ordering is defined independent of the requested document type and does not require the ordering field to be contained in the document. If no order parameter is given, ordering of results is undefined.

  • offset

    Skip the given number of relays and/or bridges. Relays are skipped first, then bridges. Non-positive offset values are treated as zero and don't change the result.

  • limit

    Limit result to the given number of relays and/or bridges. Relays are kept first, then bridges. Non-positive limit values are treated as zero and lead to an empty result. When used together with offset, the offsetting step precedes the limiting step.


Responses #

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

  • version string required

    Onionoo protocol version string.

  • next_major_version_scheduled string optional

    UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to be deployed. Omitted if no major protocol changes are planned.

  • relays_published string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when the last known relay network status consensus started being valid. Indicates how recent the relay objects in this document are.

  • relays_skipped new number optional

    Number of skipped relays as requested by a positive "offset" parameter value. Omitted if zero. Added on January 27, 2017.

  • relays array of objects required

    Array of relay objects as specified below.

  • relays_truncated new number optional

    Number of truncated relays as requested by a positive "limit" parameter value. Omitted if zero. Added on January 27, 2017.

  • bridges_published string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when the last known bridge network status was published. Indicates how recent the bridge objects in this document are.

  • bridge_skipped new number optional

    Number of skipped bridges as requested by a positive "offset" parameter value. Omitted if zero. Added on January 27, 2017.

  • bridges array of objects required

    Array of bridge objects as specified below.

  • bridges_truncated new number optional

    Number of truncated bridges as requested by a positive "limit" parameter value. Omitted if zero. Added on January 27, 2017.


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:

  • n string optional

    Relay nickname consisting of 1–19 alphanumerical characters. Omitted if the relay nickname is "Unnamed".

  • f string required

    Relay fingerprint consisting of 40 upper-case hexadecimal characters.

  • a array of strings required

    Array of IPv4 or IPv6 addresses where the relay accepts onion-routing connections or which the relay used to exit to the Internet in the past 24 hours. The first address is the primary onion-routing address that the relay used to register in the network, subsequent addresses are in arbitrary order. IPv6 hex characters are all lower-case.

  • r boolean required

    Boolean field saying whether this relay was listed as running in the last relay network status consensus.

Bridge summary objects

Bridge summary objects contain the following key-value pairs:

  • n string optional

    Bridge nickname consisting of 1–19 alphanumerical characters. Omitted if the bridge nickname is "Unnamed".

  • h string required

    SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters.

  • r boolean required

    Boolean field saying whether this bridge was listed as running in the last bridge network status.


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:

  • nickname string optional

    Relay nickname consisting of 1–19 alphanumerical characters. Omitted if the relay nickname is "Unnamed".

  • fingerprint string required

    Relay fingerprint consisting of 40 upper-case hexadecimal characters.

  • or_addresses array of strings required

    Array of IPv4 or IPv6 addresses and TCP ports or port lists where the relay accepts onion-routing connections. The first address is the primary onion-routing address that the relay used to register in the network, subsequent addresses are in arbitrary order. IPv6 hex characters are all lower-case.

  • exit_addresses array of strings optional

    Array of IPv4 or IPv6 addresses that the relay used to exit to the Internet in the past 24 hours. IPv6 hex characters are all lower-case. Only those addresses are listed that are different from onion-routing addresses. Omitted if array is empty.

  • dir_address string optional

    IPv4 address and TCP port where the relay accepts directory connections. Omitted if the relay does not accept directory connections.

  • last_seen string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when this relay was last seen in a network status consensus.

  • last_changed_address_or_port string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when this relay last stopped announcing an IPv4 or IPv6 address or TCP port where it previously accepted onion-routing or directory connections. This timestamp can serve as indicator whether this relay would be a suitable fallback directory.

  • first_seen string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when this relay was first seen in a network status consensus.

  • running boolean required

    Boolean field saying whether this relay was listed as running in the last relay network status consensus.

  • hibernating boolean optional

    Boolean field saying whether this relay indicated that it is hibernating in its last known server descriptor. This information may be helpful to decide whether a relay that is not running anymore has reached its accounting limit and has not dropped out of the network for another, unknown reason. Omitted if either the relay is not hibernating, or if no information is available about the hiberation status of the relay.

  • flags array of strings optional

    Array of relay flags that the directory authorities assigned to this relay. May be omitted if empty.

  • country string optional

    Two-letter lower-case country code as found in a GeoIP database by resolving the relay's first onion-routing IP address. Omitted if the relay IP address could not be found in the GeoIP database.

  • country_name string optional

    Country name as found in a GeoIP database by resolving the relay's first onion-routing IP address. Omitted if the relay IP address could not be found in the GeoIP database, or if the GeoIP database did not contain a country name.

  • region_name string optional

    Region name as found in a GeoIP database by resolving the relay's first onion-routing IP address. Omitted if the relay IP address could not be found in the GeoIP database, or if the GeoIP database did not contain a region name.

  • city_name string optional

    City name as found in a GeoIP database by resolving the relay's first onion-routing IP address. Omitted if the relay IP address could not be found in the GeoIP database, or if the GeoIP database did not contain a city name.

  • latitude number optional

    Latitude as found in a GeoIP database by resolving the relay's first onion-routing IP address. Omitted if the relay IP address could not be found in the GeoIP database.

  • longitude number optional

    Longitude as found in a GeoIP database by resolving the relay's first onion-routing IP address. Omitted if the relay IP address could not be found in the GeoIP database.

  • as_number string optional

    AS number as found in an AS database by resolving the relay's first onion-routing IP address. AS number strings start with "AS", followed directly by the AS number. Omitted if the relay IP address could not be found in the AS database.

  • as_name string optional

    AS name as found in an AS database by resolving the relay's first onion-routing IP address. Omitted if the relay IP address could not be found in the AS database.

  • consensus_weight number required

    Weight assigned to this relay by the directory authorities that clients use in their path selection algorithm. The unit is arbitrary; currently it's kilobytes per second, but that might change in the future.

  • host_name string optional

    Host name as found in a reverse DNS lookup of the relay IP address. This field is updated at most once in 12 hours, unless the relay IP address changes. Omitted if the relay IP address was not looked up or if no lookup request was successful yet.

  • last_restarted string optional

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when the relay was last (re-)started. Missing if router descriptor containing this information cannot be found.

  • bandwidth_rate number optional

    Average bandwidth in bytes per second that this relay is willing to sustain over long periods. Missing if router descriptor containing this information cannot be found.

  • bandwidth_burst number optional

    Bandwidth in bytes per second that this relay is willing to sustain in very short intervals. Missing if router descriptor containing this information cannot be found.

  • observed_bandwidth number optional

    Bandwidth estimate in bytes per second of the capacity this relay can handle. The relay remembers the maximum bandwidth sustained output over any ten second period in the past day, and another sustained input. The "observed_bandwidth" value is the lesser of these two numbers. Missing if router descriptor containing this information cannot be found.

  • advertised_bandwidth number optional

    Bandwidth in bytes per second that this relay is willing and capable to provide. This bandwidth value is the minimum of bandwidth_rate, bandwidth_burst, and observed_bandwidth. Missing if router descriptor containing this information cannot be found.

  • exit_policy array of strings optional

    Array of exit-policy lines. Missing if router descriptor containing this information cannot be found. May contradict the "exit_policy_summary" field in a rare edge case: this happens when the relay changes its exit policy after the directory authorities summarized the previous exit policy.

  • exit_policy_summary object optional

    Summary version of the relay's exit policy containing a dictionary with either an "accept" or a "reject" element. If there is an "accept" ("reject") element, the relay accepts (rejects) all TCP ports or port ranges in the given list for most IP addresses and rejects (accepts) all other ports. May contradict the "exit_policy" field in a rare edge case: this happens when the relay changes its exit policy after the directory authorities summarized the previous exit policy.

  • exit_policy_v6_summary object optional

    Summary version of the relay's IPv6 exit policy containing a dictionary with either an "accept" or a "reject" element. If there is an "accept" ("reject") element, the relay accepts (rejects) all TCP ports or port ranges in the given list for most IP addresses and rejects (accepts) all other ports. Missing if the relay rejects all connections to IPv6 addresses. May contradict the "exit_policy_summary" field in a rare edge case: this happens when the relay changes its exit policy after the directory authorities summarized the previous exit policy.

  • contact string optional

    Contact address of the relay operator. Omitted if empty or if descriptor containing this information cannot be found.

  • platform string optional

    Platform string containing operating system and Tor version details. Omitted if empty or if descriptor containing this information cannot be found.

  • recommended_version boolean optional

    Boolean field saying whether the Tor software version of this relay is recommended by the directory authorities or not. Omitted if either the directory authorities did not recommend versions, or the relay did not report which version it runs.

  • effective_family array of strings optional

    Array of $-prefixed fingerprints of relays that are in an effective, mutual family relationship with this relay. These relays are part of this relay's family and they consider this relay to be part of their family. Omitted if empty or if descriptor containing this information cannot be found.

  • alleged_family array of strings optional

    Array of $-prefixed fingerprints of relays that are not in an effective, mutual family relationship with this relay. These relays are part of this relay's family but they don't consider this relay to be part of their family. Omitted if empty or if descriptor containing this information cannot be found.

  • indirect_family array of strings optional

    Array of $-prefixed fingerprints of relays that are not in an effective, mutual family relationship with this relay but that can be reached by following effective, mutual family relationships starting at this relay. Omitted if empty or if descriptor containing this information cannot be found.

  • consensus_weight_fraction number optional

    Fraction of this relay's consensus weight compared to the sum of all consensus weights in the network. This fraction is a very rough approximation of the probability of this relay to be selected by clients. Omitted if the relay is not running.

  • guard_probability number optional

    Probability of this relay to be selected for the guard position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation. Omitted if the relay is not running, or the consensus does not contain bandwidth weights.

  • middle_probability number optional

    Probability of this relay to be selected for the middle position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation. Omitted if the relay is not running, or the consensus does not contain bandwidth weights.

  • exit_probability number optional

    Probability of this relay to be selected for the exit position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation. Omitted if the relay is not running, or the consensus does not contain bandwidth weights.

  • measured boolean optional

    Boolean field saying whether the consensus weight of this relay is based on a threshold of 3 or more measurements by Tor bandwidth authorities. Omitted if the network status consensus containing this relay does not contain measurement information.

Bridge details objects

Bridge details objects contain the following key-value pairs:

  • nickname string optional

    Bridge nickname consisting of 1–19 alphanumerical characters. Omitted if the bridge nickname is "Unnamed".

  • hashed_fingerprint string required

    SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters.

  • or_addresses array of strings required

    Array of sanitized IPv4 or IPv6 addresses and TCP ports or port lists where the bridge accepts onion-routing connections. The first address is the primary onion-routing address that the bridge used to register in the network, subsequent addresses are in arbitrary order. IPv6 hex characters are all lower-case. Sanitized IP addresses are always in 10/8 or [fd9f:2e19:3bcf/48] IP networks and are only useful to learn which IP version the bridge uses and to detect whether the bridge changed its address. Sanitized IP addresses always change on the 1st of every month at 00:00:00 UTC, regardless of the bridge actually changing its IP address. TCP ports are not sanitized.

  • last_seen string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when this bridge was last seen in a bridge network status.

  • first_seen string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when this bridge was first seen in a bridge network status.

  • running boolean required

    Boolean field saying whether this bridge was listed as running in the last bridge network status.

  • flags array of strings optional

    Array of relay flags that the bridge authority assigned to this bridge. May be omitted if empty.

  • last_restarted string optional

    UTC timestamp (YYYY-MM-DD hh:mm:ss) when the bridge was last (re-)started. Missing if router descriptor containing this information cannot be found.

  • advertised_bandwidth number optional

    Bandwidth in bytes per second that this bridge is willing and capable to provide. This bandwidth value is the minimum of bandwidth_rate, bandwidth_burst, and observed_bandwidth. Missing if router descriptor containing this information cannot be found.

  • platform string optional

    Platform string containing operating system and Tor version details. Omitted if not provided by the bridge or if descriptor containing this information cannot be found.

  • transports array of strings optional

    Array of (pluggable) transport names supported by this bridge.


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:

  • first string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) of the first data point, or more specifically the interval midpoint of the first interval.

  • last string required

    UTC timestamp (YYYY-MM-DD hh:mm:ss) of the last data point, or more specifically the interval midpoint of the last interval.

  • interval number required

    Time interval between two data points in seconds.

  • factor number required

    Factor by which subsequent data values need to be multiplied to obtain original values. The idea is to reduce document size while still providing sufficient detail for very different data scales.

  • count number optional

    Number of provided data points, included mostly for debugging purposes. Can also be derived from the number of elements in the subsequent array.

  • values array of numbers required

    Array of normalized values between 0 and 999. May contain null values. Contains at least two subsequent non-null values to enable drawing of line graphs.


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:

  • fingerprint string required

    Relay fingerprint consisting of 40 upper-case hexadecimal characters.

  • write_history object optional

    Object containing graph history objects with written bytes for different time periods. Keys are string representation of the time period covered by the graph history object. Keys are fixed strings "3_days", "1_week", "1_month", "3_months", "1_year", and "5_years". Keys refer to the last known bandwidth history of a relay, not to the time when the bandwidth document was published. A graph history object is only contained if the time period it covers is not already contained in another graph history object with shorter time period and higher data resolution. Similarly, a graph history object is excluded if the relay did not provide bandwidth histories on the required level of detail. The unit is bytes per second. Contained graph history objects may contain null values if the relay did not provide any bandwidth data or only data for less than 20% of a given time period.

  • read_history object optional

    Object containing graph history objects with read bytes for different time periods. The specification of graph history objects is similar to those in the write_history field.

Bridge bandwidth objects

Bridge bandwidth objects contain the following key-value pairs:

  • fingerprint string required

    SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters.

  • write_history object optional

    Object containing graph history objects with written bytes for different time periods. The specification of graph history objects is similar to those in the write_history field of relays.

  • read_history object optional

    Object containing graph history objects with read bytes for different time periods. The specification of graph history objects is similar to those in the write_history field of relays.


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:

  • fingerprint string required

    Relay fingerprint consisting of 40 upper-case hexadecimal characters.

  • consensus_weight_fraction object optional

    History object containing the fraction of this relay's consensus weight compared to the sum of all consensus weights in the network. This fraction is a very rough approximation of the probability of this relay to be selected by clients. Keys are string representation of the time period covered by the graph history object. Keys are fixed strings "1_week", "1_month", "3_months", "1_year", and "5_years". Keys refer to the last known weights history of a relay, not to the time when the weights document was published. A graph history object is only contained if the time period it covers is not already contained in another graph history object with shorter time period and higher data resolution. The unit is path-selection probability. Contained graph history objects may contain null values if the relay was running less than 20% of a given time period.

  • guard_probability object optional

    History object containing the probability of this relay to be selected for the guard position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation. The specification of this history object is similar to that in the consensus_weight_fraction field above.

  • middle_probability object optional

    History object containing the probability of this relay to be selected for the middle position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation. The specification of this history object is similar to that in the consensus_weight_fraction field above.

  • exit_probability object optional

    History object containing the probability of this relay to be selected for the exit position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation. The specification of this history object is similar to that in the consensus_weight_fraction field above.

  • consensus_weight object optional

    History object containing the absolute consensus weight of this relay. The specification of this history object is similar to that in the consensus_weight_fraction field above.


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:

  • fingerprint string required

    SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters.

  • average_clients object optional

    Object containing graph history objects with the average number of clients connecting to this bridge. Keys are string representation of the time period covered by the graph history object. Keys are fixed strings "1_week", "1_month", "3_months", "1_year", and "5_years". Keys refer to the last known clients history of a bridge, not to the time when the clients document was published. A graph history object is only contained if the time period it covers is not already contained in another clients graph object with shorter time period and higher data resolution. The unit is number of clients. Contained graph history objects may contain null values if the bridge did not report client statistics for at least 50% of a given time period. Each graph history object contains the following additional key-value pairs:

    • countries beta object optional

      Object containing fractions of clients by country in the considered time period. Keys are two-letter lower-case country codes as found in a GeoIP database. Values are numbers between 0 and 1 standing for the fraction of clients by country. A country is only included if at least 1% of clients came from this country. Omitted if the bridge did not report client statistics by country. BETA: This field breaks compatibility with the history objects contained in other documents pretty badly. It might be removed in the future without notice.

    • transports beta object optional

      Object containing fractions of clients by transport in the considered time period. Keys are transport names, or "<OR>" for the default onion-routing transport protocol. Values are numbers between 0 and 1 standing for the fraction of clients by transport. Omitted if the bridge did not report client statistics by transport. BETA: This field breaks compatibility with the history objects contained in other documents pretty badly. It might be removed in the future without notice.

    • versions beta object optional

      Object containing fractions of clients by IP version in the considered time period. Keys are either "v4" for IPv4 or "v6" for IPv6. Values are numbers between 0 and 1 standing for the fraction of clients by version. Omitted if the bridge did not report client statistics by IP version. BETA: This field breaks compatibility with the history objects contained in other documents pretty badly. It might be removed in the future without notice.


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:

  • fingerprint string required

    Relay fingerprint consisting of 40 upper-case hexadecimal characters.

  • uptime object optional

    Object containing graph history objects with the fractional uptime of this relay. Keys are string representation of the time period covered by the graph history object. Keys are fixed strings "1_week", "1_month", "3_months", "1_year", and "5_years". Keys refer to the last known uptime history of a relay, not to the time when the uptime document was published. A graph history object is only contained if the time period it covers is not already contained in another graph history object with shorter time period and higher data resolution. The unit is fractional uptime from 0 to 1. Contained graph history objects may contain null values if less than 20% of network statuses have been processed for a given time period.

  • flags object optional

    Object containing fractional times of this relay having relay flags assigned. Keys are flag names like "Running" or "Exit", values are objects similar to the uptime field above, again with keys like "1_week" etc. If a relay never had a given relay flag assigned, no object is included for that flag.

Bridge uptime objects

Bridge uptime objects contain the following key-value pairs:

  • fingerprint string required

    SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters.

  • uptime object optional

    Object containing uptime history objects for different time periods. The specification of uptime history objects is similar to those in the uptime field of relays.


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

Contact

Data on this site is freely available under a CC0 no copyright declaration: 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 registered trademarks of The Tor Project, Inc.