Skip to main content

Looking Glass

Looking Glass provides two independent measurements:

  • Manual Ping, Traceroute and MTR: from a selected location to your public IP address or domain.
  • HTTPS latency: directly from the visitor's browser to a location. This is HTTPS round-trip time, not ICMP ping.

Get the points​

Call GET /looking-glass/points from your backend with X-Api-Key and api_key_id. The integration's IP allowlist applies. Use optional location_id to filter; no matches return an empty list.

Each point contains its ID, location, country, city, public test IPs, ipv4_enabled, ipv6_enabled, supported checks and three nullable latency URLs. Use the registry response rather than a fixed list of locations or addresses.

Disabled points remain listed. An IP being present does not mean diagnostics are enabled. The URLs are:

FieldPurpose
latency_urlDefault measurement; the browser chooses a family when both are enabled. If only one is enabled, its URL is returned.
latency_ipv4_urlIPv4-only measurement.
latency_ipv6_urlIPv6-only measurement.

A disabled family or missing hostname returns null. A visitor without IPv6 may still reach the location over IPv4.

Run a manual check​

Call POST /looking-glass/check only when the user starts a diagnostic:

curl --request POST 'https://cloud-api.adaptgroup.pro/looking-glass/check' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--max-time 60 \
--data '{"api_key_id":1,"point_id":1,"type":"ping","family":4,"target":"1.1.1.1"}'

type is ping, traceroute or mtr; family must be the integer 4 or 6. The target is a public numeric IP or domain without a protocol, port, path or query. A numeric IP must match the selected family. Domains are resolved in the selected location. Internal and infrastructure destinations, including domains resolving to them, are rejected.

The call is synchronous. Allow 60 seconds in your HTTP client. Do not automatically retry after a disconnect or HTTP 504: the diagnostic may have executed. This route does not use Idempotency-Key.

The response includes the actual tested IP in target, command return_code, timed_out, execution duration_ms and output. Execution time is not network latency. Ping and Traceroute output is text; MTR output is a JSON string. Handle JSON parsing failures and keep a text fallback. Render output as text, never HTML.

HTTP 200 can contain a nonzero command exit code or an incomplete result: timed_out=true, return_code=null. Asterisks, unanswered ICMP packets or a nonzero exit code do not prove that the entire location is unavailable.

Limits and errors​

Manual-check quotas are independent for each integration. Rate limits use a rolling 60-second window; all limits apply together:

ScopeChecks per minuteConcurrent checks
API integration, all points3004
Integration + source IP302
Integration + normalized target60—
Integration + point1202

Each regional point also limits an integration to 120 checks per minute and an integration + resolved target IP to 60 per minute. Different domains resolving to the same IP share this target quota. IPv6 source addresses are grouped by /64 within an integration. When requests come through your backend, visitors share its source-IP limit across all locations within your integration. Another integration using the same IP has its own quota. Arbitrary client_ip or api_id fields are not accepted.

A point runs up to four checks at once, with at most two from one integration. When slots are occupied, requests wait up to five seconds in a queue that serves integrations in rounds. Each integration can have at most two waiting requests per point. Waiting or rejected requests do not consume the rate quota; it is consumed when execution is admitted. Capacity is shared, so the quota is not a guarantee of 300 completed checks per minute. A full queue or expired wait returns HTTP 429 with Retry-After: 60. The request remains synchronous and returns no job ID; queued checks are not started in the background after the waiting request ends.

HTTPCode / meaning
401Invalid Cloud API authentication.
403ip_not_allowed: source IP is outside the integration allowlist.
404lg_point_not_found: unknown point.
409lg_point_disabled: point or family disabled.
422Request validation error, or lg_invalid_target: forbidden target or DNS resolution failure.
429lg_rate_limited: personal quota reached, point capacity unavailable, queue full or waiting time expired. Respect Retry-After, currently 60 seconds.
502lg_agent_unavailable: point unavailable or invalid result.
503lg_unavailable: service unavailable; lg_client_ip_unavailable: source IP could not be determined.
504lg_timeout: no diagnostic response before the deadline.

Do not start an automatic retry loop after 429. Allow a new user-initiated check after Retry-After. Diagnostic results are not cached or stored as history by this API.

Measure browser HTTPS latency​

Your backend supplies the point list to the frontend. The browser then calls the provided latency URL directly, without an API key or cookies. Proxying this request through your backend would measure its connection instead of the visitor's.

  1. Run one measurement cycle when the page opens, with at most three locations in parallel. Skip disabled points and null URLs.
  2. For each location, send one warm-up request, followed by five sequential samples. Exclude the warm-up, which may include DNS/TCP/TLS setup.
  3. Give each request a three-second timeout. Display the median if at least three samples succeed; otherwise show “Measurement unavailable”.
  4. On HTTP 429, stop measuring that point and show “Try again later”. Do not retry automatically.
  5. Measure only latency_url by default. Use the IPv4/IPv6-specific URLs only when selected by the user.
  6. Cancel requests with AbortController when leaving the page. Do not restart on each render or use a background interval. Results may be retained in tab memory for 60 seconds; a separate action can start another measurement.

Each request uses a unique query parameter and these fetch options:

const probeUrl = new URL(point.latency_url);
probeUrl.searchParams.set('probe', crypto.randomUUID());
const response = await fetch(probeUrl, {
credentials: 'omit',
cache: 'no-store',
mode: 'cors',
redirect: 'error',
signal: AbortSignal.any([pageAbortController.signal, AbortSignal.timeout(3000)]),
});
await response.arrayBuffer();

The endpoint returns an empty HTTP 200 with CORS and Timing-Allow-Origin support. Inspect the status; do not use no-cors, which hides errors and 429 responses. Use Resource Timing responseEnd - requestStart when available, or elapsed performance.now() time around fetch and body reading. The fallback includes additional browser overhead. Do not clear the page's shared Resource Timing entries.

Allow https://*.lg.adaptgroup.pro in your frontend CSP connect-src. Label the result “HTTPS latency”. HTTP timeouts are not ICMP packet loss and do not establish a location outage.

These requests do not consume manual-diagnostic quotas. Their separate per-point limits are 20 requests/second per source IP with burst 40, 500/second per point with burst 100, and 8 concurrent requests per IP / 128 per point. Visitors behind the same NAT share its limits.

© 2026 AdaptGroup LLC. All rights reserved.
30 N Gould St Ste R, Sheridan, WY 82801, USA
Back to top