RIPE Atlas Documentation

The definitions Array ​

The definitions array holds single objects, which we will refer to as measurement definitions.

A measurement definition has a similar structure to a measurement specification. The measurement specification, as you might recall, is the collection of measurement settings that a probe needs to perform a measurement. There are some base attributes and some type-specific attributes in the specification.

A measurement definition is a sub-set of the measurement specification. There are some required fields, but most are optional. RIPE Atlas will fill out the missing fields with defaults for all non-required fields. Which fields are required differs per measurement type.

These are the required fields for all measurement types:

  • description: An arbitrary string you will use to refer to this measurement.
  • type: One of ping,traceroute,dns, sslcert or ntp
  • af: The address family. It must be either 4 or 6.

Additionally:

  • target is required for all types except DNS, which instead requires query_argument.

Optional fields ​

These are the optional fields for all measurement types:

  • interval: Frequency in seconds between each measurement. Ignored for one-off measurements.
  • spread: Spread time (in seconds) to stagger measurement start times across probes.
  • tags: An array of user-defined strings to annotate and organize measurements. These are different from probe tags and can be used for filtering or grouping measurements in user interfaces.
  • skip_dns_check: Boolean. If true, the measurement target will not be DNS-validated before measurement.
  • resolve_on_probe: Boolean. If true, DNS resolution of the target will happen on the probe rather than centrally.

Type-specific fields ​

Each measurement type supports additional fields specific to its operation:

ping ​

  • packets: Number of packets to send (default: 3)
  • size: Size of each packet in bytes (default: 48)
  • packet_interval: Time in milliseconds between packets
  • include_probe_id: Boolean. Include the probe ID in the payload

traceroute ​

  • packets: Packets sent per hop
  • size: Packet size
  • protocol: UDP, ICMP, or TCP
  • first_hop: Starting hop number
  • max_hops: Maximum hops to trace
  • response_timeout: Timeout in milliseconds
  • paris: Paris traceroute ID
  • dont_fragment: Boolean to set the "Don't Fragment" bit
  • destination_option_size, hop_by_hop_option_size: IPv6 extension header sizes
  • port: TCP destination port if protocol is TCP

dns ​

  • query_argument: DNS name to be queried (required)
  • target: Optional DNS resolver to use (instead of system default)
  • query_class: DNS class (e.g. IN, CHAOS)
  • query_type: Record type (e.g. A, AAAA, MX)
  • udp_payload_size: UDP buffer size
  • retry: Number of retry attempts
  • use_probe_resolver: Boolean
  • set_rd_bit, set_cd_bit, set_do_bit, set_nsid_bit: DNS header flags
  • include_qbuf, include_abuf: Include request/response buffers

⚠️ Note: For privacy reasons, when use_probe_resolver is set to true, the attribute set_rd_bit is silently set to true even if not explicitly specified.

sslcert ​

  • hostname: The SNI hostname to send in the TLS handshake
  • port: The port to connect to (usually 443)

http ​

  • path: HTTP path (default: /)
  • method: HTTP method (GET, POST, etc.)
  • header_bytes: Limit on returned header bytes
  • extended_timing: Boolean
  • more_extended_timing: Boolean
  • port: Port number to connect to
  • version: HTTP version (1.1, etc.)

ntp ​

  • packets: Number of NTP packets to send
  • timeout: Timeout in milliseconds

Notes ​

  • The tags array is included per definition, enabling tagging of each measurement independently.
  • Multiple measurement definitions can be submitted as part of a single request when targeting different protocols or configurations.