Sign in
Measurements

Create a measurement

Creates a new measurement with parameters set in the request body. The measurement runs asynchronously and you can retrieve its current state at the URL returned in the Location header.

Client guidelines

  • If the application is running in interactive mode, set the inProgressUpdates option to true to have the API return partial results as soon as they are available. This allows the user to see the measurement progress in real time.
    • If the application is interactive by default but also implements a "CI" mode for scripting, do not set the flag in the CI mode.
  • To perform multiple measurements using exactly the same probes, create a single measurement first, then pass its id in the locations field for the other measurements.
  • When you receive a 429 response, inform the user about their current rate limit status based on the response headers. Depending on the exact situation and on what your application supports, you may also suggest:
    • Signing in or using an access token.
    • Learning more about how to get additional credits at https://globalping.io/credits.
    • Repeating the measurement with fewer probes.
post/v1/measurements

Request

  • Base URL: https://api.globalping.io
  • URL: https://api.globalping.io/v1/measurements
  • Auth: one of:
    • none
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://auth.globalping.io/oauth/authorize, token URL https://auth.globalping.io/oauth/token, scopes: measurements)

Request body

type'ping' | 'traceroute' | 'dns' | 'mtr' | 'http' required

The measurement type.

targetstring required

A publicly reachable measurement target. Typically a hostname, an IPv4 address, or IPv6 address, depending on the measurement type. Support for IPv6 targets is currently considered experimental.

inProgressUpdatesboolean

Indicates whether you want to get partial results while the measurement is still running:

  • 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.
  • If false, the result of each test is updated only after the test finishes.
limitinteger

The maximum number of probes that should run the measurement. The result count might be lower if there aren't enough probes available in the specified locations. Mutually exclusive with the limit property that can be set for individual locations. Non-authenticated requests are limited to a maximum of 50 probes.

timeoutinteger

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. In 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.

Response

If the API accepted the request for processing, it returns status 202 Accepted and a body containing the ID of the newly created measurement. You can use the URL from the Location header to retrieve the measurement status.

idstring required

The measurement ID.

Tip: You can use the ID to create a new measurement request, reusing the same probes.

probesCountinteger required

The actual number of probes that performed the measurement tests. Smaller or equal to limit, depending on probe availability.

Changes

No recorded changes to this operation across all 1 revision of this API.