MeasurementRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/globalping-io/json-schema/globalping-io-measurement-request-schema.json",
  "title": "MeasurementRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/globalping-io-openapi.yaml#/components/schemas/MeasurementRequest",
  "allOf": [
    {
      "$ref": "#/$defs/MeasurementOptionsConditions"
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "target"
      ],
      "properties": {
        "type": {
          "$ref": "#/$defs/MeasurementType"
        },
        "target": {
          "$ref": "#/$defs/MeasurementTarget"
        },
        "inProgressUpdates": {
          "type": "boolean",
          "description": "Indicates whether you want to get partial results while the measurement is still running:\n- If `true`, partial results are returned as soon as they are available, and you can present them to the user in real time. Note that only the first 5 tests from the `results` array will update in real time.\n- If `false`, the result of each test is updated only after the test finishes.\n",
          "default": false
        },
        "locations": {
          "$ref": "#/$defs/MeasurementLocations"
        },
        "limit": {
          "allOf": [
            {
              "$ref": "#/$defs/MeasurementLimit"
            }
          ],
          "default": 1
        },
        "timeout": {
          "type": "integer",
          "minimum": 5,
          "maximum": 30,
          "description": "The probe-side wall-clock timeout for each test, in seconds. If omitted, the value is calculated based on the provided measurement options and can be up to 30 seconds.\nIn all cases, callers should allow at least 10 additional seconds for probe-to-API communication and API measurement finalization before triggering a client-side timeout.\n"
        },
        "measurementOptions": {
          "$ref": "#/$defs/MeasurementOptions"
        }
      }
    }
  ],
  "$defs": {
    "AsnCode": {
      "type": "integer",
      "minimum": 1,
      "description": "An autonomous system number (ASN)."
    },
    "CityName": {
      "type": "string",
      "description": "A city name in English."
    },
    "ContinentCode": {
      "type": "string",
      "description": "A two-letter continent code.",
      "enum": [
        "AF",
        "AN",
        "AS",
        "EU",
        "NA",
        "OC",
        "SA"
      ]
    },
    "CountryCode": {
      "type": "string",
      "description": "A two-letter country code based on [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)."
    },
    "DnsMeasurementResolver": {
      "description": "A DNS resolver to use for the query. Defaults to the probe system resolver.",
      "anyOf": [
        {
          "type": "string",
          "format": "ipv4",
          "description": "The IPv4 address of the resolver."
        },
        {
          "type": "string",
          "format": "ipv6",
          "description": "EXPERIMENTAL: The IPv6 address of the resolver.\n"
        },
        {
          "type": "string",
          "format": "hostname",
          "description": "The Fully Qualified Domain Name (FQDN) of the resolver."
        }
      ]
    },
    "DnsProtocol": {
      "type": "string",
      "description": "The protocol to use for the DNS query.",
      "enum": [
        "TCP",
        "UDP"
      ],
      "default": "UDP"
    },
    "DnsQueryType": {
      "type": "string",
      "description": "The type of DNS query.",
      "enum": [
        "A",
        "AAAA",
        "ANY",
        "CNAME",
        "DNSKEY",
        "DS",
        "HTTPS",
        "MX",
        "NS",
        "NSEC",
        "PTR",
        "RRSIG",
        "SOA",
        "TXT",
        "SRV",
        "SVCB"
      ],
      "default": "A"
    },
    "HttpMeasurementResolver": {
      "description": "A DNS resolver to use for the query. Defaults to the probe system resolver.",
      "anyOf": [
        {
          "type": "string",
          "format": "ipv4",
          "description": "The IPv4 address of the resolver."
        },
        {
          "type": "string",
          "format": "ipv6",
          "description": "EXPERIMENTAL: The IPv6 address of the resolver.\n"
        }
      ]
    },
    "HttpProtocol": {
      "type": "string",
      "description": "The protocol to use for the HTTP request.",
      "enum": [
        "HTTP",
        "HTTPS",
        "HTTP2"
      ],
      "default": "HTTPS"
    },
    "HttpRequestMethod": {
      "type": "string",
      "description": "The HTTP method to use.",
      "enum": [
        "HEAD",
        "GET",
        "OPTIONS"
      ],
      "default": "HEAD"
    },
    "IpVersion": {
      "type": "integer",
      "description": "EXPERIMENTAL: The IP version to use. Only allowed if the target is a hostname.\n",
      "enum": [
        4,
        6
      ],
      "default": 4
    },
    "MeasurementDnsOptions": {
      "type": "object",
      "title": "DnsOptions",
      "additionalProperties": false,
      "properties": {
        "query": {
          "type": "object",
          "description": "The DNS query properties.",
          "additionalProperties": false,
          "properties": {
            "type": {
              "$ref": "#/$defs/DnsQueryType"
            }
          }
        },
        "resolver": {
          "$ref": "#/$defs/DnsMeasurementResolver"
        },
        "protocol": {
          "$ref": "#/$defs/DnsProtocol"
        },
        "port": {
          "type": "integer",
          "description": "The port number to send the query to.",
          "minimum": 0,
          "maximum": 65535,
          "default": 53
        },
        "ipVersion": {
          "$ref": "#/$defs/IpVersion"
        },
        "trace": {
          "type": "boolean",
          "description": "Toggles tracing of the delegation path from the root servers down to the target domain name.\n",
          "default": false
        }
      }
    },
    "MeasurementHttpOptions": {
      "type": "object",
      "title": "HttpOptions",
      "additionalProperties": false,
      "properties": {
        "request": {
          "type": "object",
          "description": "The HTTP request properties.",
          "additionalProperties": false,
          "properties": {
            "host": {
              "type": "string",
              "description": "An optional override for the `Host` header. The default value is based on the `target`.\n"
            },
            "path": {
              "type": "string",
              "description": "The path portion of the URL."
            },
            "query": {
              "type": "string",
              "description": "The query string portion of the URL."
            },
            "method": {
              "$ref": "#/$defs/HttpRequestMethod"
            },
            "headers": {
              "type": "object",
              "description": "Additional request headers. Note that the `Host` and `User-Agent` are reserved and internally overridden.\n",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        },
        "resolver": {
          "$ref": "#/$defs/HttpMeasurementResolver"
        },
        "protocol": {
          "$ref": "#/$defs/HttpProtocol"
        },
        "port": {
          "type": "integer",
          "description": "The port number to use. Defaults to `443` for `HTTPS` and `HTTP2`, `80` for `HTTP`.",
          "minimum": 0,
          "maximum": 65535
        },
        "ipVersion": {
          "$ref": "#/$defs/IpVersion"
        }
      }
    },
    "MeasurementLimit": {
      "type": "integer",
      "description": "The maximum number of probes that should run the measurement.\nThe result count might be lower if there aren't enough probes available in the specified locations.\nMutually exclusive with the `limit` property that can be set for individual locations.\nNon-authenticated requests are limited to a maximum of 50 probes.\n",
      "minimum": 1,
      "maximum": 500
    },
    "MeasurementLocationOption": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "continent": {
          "$ref": "#/$defs/ContinentCode"
        },
        "region": {
          "$ref": "#/$defs/RegionName"
        },
        "country": {
          "$ref": "#/$defs/CountryCode"
        },
        "state": {
          "$ref": "#/$defs/StateCode"
        },
        "city": {
          "$ref": "#/$defs/CityName"
        },
        "asn": {
          "$ref": "#/$defs/AsnCode"
        },
        "network": {
          "$ref": "#/$defs/NetworkName"
        },
        "tags": {
          "$ref": "#/$defs/Tags"
        },
        "magic": {
          "type": "string",
          "description": "Locations defined in a single string instead of the respective location properties.\nThe API performs fuzzy matching on the `country`, `city`, `state` (using `US-` prefix, e.g., `US-NY`), `continent`, `region`, `asn` (using `AS` prefix, e.g., `AS123`), `tags`, and `network` values.\nSupports full names, ISO codes (where applicable), and common aliases.\nMultiple conditions can be combined using the `+` character, which behaves as a logical `AND`.\n\nNote that in some cases, the names of cities, states, and countries, as well as the ISO codes of countries and continents, overlap. Additionally, city names are not unique across countries.\nWe recommend that you:\n - refer to US states via their full [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US) codes, e.g., `US-NY`,\n - refer to cities in combination with their country or US state,\n - refer to continents by their name (not the two letter codes).\n"
        },
        "limit": {
          "type": "integer",
          "description": "The maximum number of probes that should run the measurement in this location.\nNon-authenticated requests are limited to a maximum of 50 probes.\nThe result count might be lower if there aren't enough probes available in this location.\nMutually exclusive with the global `limit` property.\n",
          "minimum": 1,
          "maximum": 500,
          "default": 1
        }
      }
    },
    "MeasurementLocations": {
      "oneOf": [
        {
          "type": "array",
          "description": "An array of locations from which to run the measurement. Each object specifies a location using one or more keys, such as country, city, ASN, etc.\n",
          "items": {
            "$ref": "#/$defs/MeasurementLocationOption"
          }
        },
        {
          "type": "string",
          "description": "The `id` of a previous measurement whose probes you want to reuse.\nThe probes are returned in the same order as in the previous measurement.\nMeasurement type and options are not reused and need to be specified in the request.\nNote that this option only works for the lifetime of the original measurement\nand will result in a `422` response for expired or invalid `id` values.\n"
        }
      ]
    },
    "MeasurementMtrOptions": {
      "type": "object",
      "title": "MtrOptions",
      "additionalProperties": false,
      "properties": {
        "packets": {
          "type": "integer",
          "description": "The number of packets to send to each hop.",
          "default": 3,
          "minimum": 1,
          "maximum": 16
        },
        "protocol": {
          "$ref": "#/$defs/MtrProtocol"
        },
        "port": {
          "type": "integer",
          "description": "The destination port for the packets. Applies only for the `TCP` and `UDP` protocols.\n",
          "minimum": 0,
          "maximum": 65535,
          "default": 80
        },
        "ipVersion": {
          "$ref": "#/$defs/IpVersion"
        }
      }
    },
    "MeasurementOptions": {
      "description": "Additional optional fields depending on the measurement `type`.",
      "anyOf": [
        {
          "$ref": "#/$defs/MeasurementPingOptions"
        },
        {
          "$ref": "#/$defs/MeasurementTracerouteOptions"
        },
        {
          "$ref": "#/$defs/MeasurementDnsOptions"
        },
        {
          "$ref": "#/$defs/MeasurementMtrOptions"
        },
        {
          "$ref": "#/$defs/MeasurementHttpOptions"
        }
      ]
    },
    "MeasurementOptionsConditions": {
      "allOf": [
        {
          "if": {
            "type": "object",
            "properties": {
              "type": {
                "const": "ping"
              }
            }
          },
          "then": {
            "type": "object",
            "properties": {
              "measurementOptions": {
                "$ref": "#/$defs/MeasurementPingOptions"
              }
            }
          }
        },
        {
          "if": {
            "type": "object",
            "properties": {
              "type": {
                "const": "traceroute"
              }
            }
          },
          "then": {
            "type": "object",
            "properties": {
              "measurementOptions": {
                "$ref": "#/$defs/MeasurementTracerouteOptions"
              }
            }
          }
        },
        {
          "if": {
            "type": "object",
            "properties": {
              "type": {
                "const": "dns"
              }
            }
          },
          "then": {
            "type": "object",
            "properties": {
              "measurementOptions": {
                "$ref": "#/$defs/MeasurementDnsOptions"
              }
            }
          }
        },
        {
          "if": {
            "type": "object",
            "properties": {
              "type": {
                "const": "mtr"
              }
            }
          },
          "then": {
            "type": "object",
            "properties": {
              "measurementOptions": {
                "$ref": "#/$defs/MeasurementMtrOptions"
              }
            }
          }
        },
        {
          "if": {
            "type": "object",
            "properties": {
              "type": {
                "const": "http"
              }
            }
          },
          "then": {
            "type": "object",
            "properties": {
              "measurementOptions": {
                "$ref": "#/$defs/MeasurementHttpOptions"
              }
            }
          }
        }
      ]
    },
    "MeasurementPingOptions": {
      "type": "object",
      "title": "PingOptions",
      "additionalProperties": false,
      "properties": {
        "packets": {
          "type": "integer",
          "description": "The number of packets to send.",
          "default": 3,
          "minimum": 1,
          "maximum": 16
        },
        "protocol": {
          "$ref": "#/$defs/PingProtocol"
        },
        "port": {
          "type": "integer",
          "description": "The destination port for the packets. Applies only for the `TCP` protocol.\n",
          "minimum": 0,
          "maximum": 65535,
          "default": 80
        },
        "ipVersion": {
          "$ref": "#/$defs/IpVersion"
        }
      }
    },
    "MeasurementTarget": {
      "type": "string",
      "description": "A publicly reachable measurement target.\nTypically a hostname, an IPv4 address, or IPv6 address, depending on the measurement `type`.\nSupport for IPv6 targets is currently considered experimental.\n"
    },
    "MeasurementTracerouteOptions": {
      "type": "object",
      "title": "TracerouteOptions",
      "additionalProperties": false,
      "properties": {
        "protocol": {
          "$ref": "#/$defs/TracerouteProtocol"
        },
        "port": {
          "type": "integer",
          "description": "The destination port for the packets. Applies only for the `TCP` protocol.\n",
          "minimum": 0,
          "maximum": 65535,
          "default": 80
        },
        "ipVersion": {
          "$ref": "#/$defs/IpVersion"
        }
      }
    },
    "MeasurementType": {
      "type": "string",
      "description": "The measurement type.",
      "enum": [
        "ping",
        "traceroute",
        "dns",
        "mtr",
        "http"
      ]
    },
    "MtrProtocol": {
      "type": "string",
      "description": "The transport protocol to use.",
      "enum": [
        "ICMP",
        "TCP",
        "UDP"
      ],
      "default": "ICMP"
    },
    "NetworkName": {
      "type": "string",
      "description": "A network name, such as \"Google LLC\" or \"DigitalOcean, LLC\"."
    },
    "PingProtocol": {
      "type": "string",
      "description": "The transport protocol to use.",
      "enum": [
        "ICMP",
        "TCP"
      ],
      "default": "ICMP"
    },
    "RegionName": {
      "type": "string",
      "description": "A geographic region name based on UN [Standard Country or Area Codes for Statistical Use (M49)](https://unstats.un.org/unsd/methodology/m49/).\n",
      "enum": [
        "Northern Africa",
        "Eastern Africa",
        "Middle Africa",
        "Southern Africa",
        "Western Africa",
        "Caribbean",
        "Central America",
        "South America",
        "Northern America",
        "Central Asia",
        "Eastern Asia",
        "South-eastern Asia",
        "Southern Asia",
        "Western Asia",
        "Eastern Europe",
        "Northern Europe",
        "Southern Europe",
        "Western Europe",
        "Australia and New Zealand",
        "Melanesia",
        "Micronesia",
        "Polynesia"
      ]
    },
    "StateCode": {
      "type": "string",
      "description": "A two-letter [US state code](https://www.faa.gov/air_traffic/publications/atpubs/cnt_html/appendix_a.html)."
    },
    "Tags": {
      "type": "array",
      "description": "An array of additional values to fine-tune probe selection:\n- Probes hosted in [AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions), [Google Cloud](https://cloud.google.com/compute/docs/regions-zones#available), [Azure](https://learn.microsoft.com/en-us/azure/reliability/regions-list), and [Oracle Cloud](https://docs.oracle.com/en-us/iaas/Content/General/Concepts/regions.htm) are automatically assigned the service region code. For example: `aws-eu-west-1`, `gcp-us-south1`, `azure-polandcentral`, and `oci-us-ashburn-1`. They are also assigned the provider name: `aws`, `gcp`, `azure`, or `oci`.\n- Probes are automatically assigned `datacenter-network` and `eyeball-network` tags to distinguish between datacenter and end-user locations.\n",
      "items": {
        "type": "string"
      }
    },
    "TracerouteProtocol": {
      "type": "string",
      "description": "The transport protocol to use.",
      "enum": [
        "ICMP",
        "TCP",
        "UDP"
      ],
      "default": "ICMP"
    }
  }
}