Want to add Globalping’s global network testing capabilities to your tool, or build a new tool on top of it using a coding agent? Then this guide is for you (and your agent). The first part explains how to use this guide and what you, the human, need to know. Below, you'll find the agent brief, which contains everything an agent needs to know about Globalping so that you can get to results faster.

How to use the agent brief

Copy the brief and provide it to your agent, either as a file or by pasting it into the chat. Then add your own request. The brief only provides context about Globalping and no task (we don’t know what you’re building). It has no placeholders for you to fill in, so it should work out of the box.

What you should know

  • Keep API tokens a secret and make sure to never put them in frontend code, repos, or logs. Also don’t paste your token into the agent chat. Instead, set it as an environment variable or secret yourself.
  • Without authenticating, you get 250 free tests per hour per IP and up to 50 probes per measurement. Create a free Globalping Dashboard account and generate an API token to increase this to 500 tests per hour and 500 probes per measurement.
  • Credits (available only to authenticated users) cover tests if you run out of free tests. You can earn them by hosting and adopting a probe in the dashboard or by sponsoring Globalping on GitHub. Limits can change, so check the credits page for current values.
  • Review the agent’s work (token handling, polling, error handling). The brief includes a checklist for the agent, but you’re still responsible for the result.
  • Our terms of use apply.

Share your integration

Are you building something public? Open an issue on the Globalping GitHub repo to get listed on the integrations page.

Globalping context for coding agents

This document is background knowledge about Globalping. It is not a task. Follow the user's request and use this document for Globalping-specific facts, decisions, and constraints. Prefer the linked sources over this document for exact details.

If a codebase already exists, follow its conventions (language, HTTP client, error handling, config and secrets handling) and, unless told otherwise, keep the Globalping code isolated in one module/service so it is easy to review and change. If there is no codebase and the user hasn't specified a structure, propose a minimal structure and confirm it before building.

1. Resource Index

Read the relevant source before writing code. This document does not duplicate them.

  • OpenAPI spec (spec.yaml): Authoritative source for request fields per measurement type, location fields, response shapes, error responses, headers, and per-endpoint "Client guidelines".
  • Globalping repo README: Platform overview, location (´magic`) syntax and best practices, probe availability rules, high-volume testing.
  • Credits & limits: Current limits and how credits work.
  • Globalping MCP server repo: MCP server that lets an agent run Globalping measurements itself. Use it (if available) to try measurements and see real results while building. Don't use it to build the integration, whose code should call the API directly.
  • Integrations page: Check whether an SDK or library already exists for the project's stack, and see existing integrations for reference.
  • globalping-go: Official client for Go projects. Prefer it over hand-written API calls, but verify it supports what you need.
  • globalping-typescript: Official client for Node.js/TypeScript projects. Prefer it over hand-written API calls, but verify it supports what you need.
  • globalping-cli: The official CLI. Useful for shell scripts or CI, and as a reference for behavior.

2. How Globalping Works

  • Globalping runs network tests from community-hosted probes distributed worldwide. Only currently online probes can be used.
  • A measurement is one test type run against one target from one or more probes. Each probe produces its own result, so results can differ between probes.
  • Measurements are asynchronous. The API accepts the request, probes run the test, and results become available shortly after. Expect an in-progress state, not an instant answer.
  • Locations describe which probes may run a test (country, city, network, tags, etc.). Probes have no public IDs, so you can't target an individual probe by ID. The API picks from the matching probes, so repeated runs can use different ones. limit sets how many probes to use.
  • Custom tags (exception): owners who adopt probes in the Globalping Dashboard can give them their own tags (a combination of the owner's GitHub username or organization and a custom string), which work as a location filter. A unique tag can effectively target a single probe, and a shared tag targets a group. GET /v1/probes lists all online probes with their tags, so a tag the user provides can be checked there. Only use custom tags if the user gives them to you.
  • Results are best effort: the API may return fewer probes than requested, and individual tests can fail or time out. Partial results are normal.
  • To run on the same probes again (e.g., for fair comparisons), pass the ID of an earlier measurement as the location. This is best effort: probes that are offline later are missing from the new results, and IDs expire (up to six months), so never hardcode them.

3. Measurement Types

Pick the type that fits what the feature needs to find out, and the simplest one that answers it.

Type Use it for
ping Reachability and latency/packet loss to a host
traceroute Seeing the network path (hops) to a host
mtr Path plus per-hop loss/latency statistics; diagnosing where a path degrades
dns Resolving DNS records from different places (like dig); comparing resolvers or checking propagation
http Fetching a URL from different places (like curl): status, headers, timing breakdown, TLS info; checking availability and CDN performance

Each type has its own set of options (e.g., DNS query type and resolver, HTTP method/path/headers). Look them up in spec.yaml; options for one type are not valid for another.

4. Auth and Limits

Numbers below are from the credits page at the time of writing. Verify against the credits page and don't hardcode them where avoidable. GET /v1/limits returns the caller's own rate limits (for the token's user if authenticated, otherwise for the IP address). Remaining credits are included only for authenticated requests.

  • No auth required to use the API. Unauthenticated limits apply per IP address: 250 tests/hour, 50 probes per measurement.
  • Browser use: Cross-origin requests are allowed (CORS *), so unauthenticated browser calls work.
  • Authenticated (API token created by the user in the Globalping Dashboard at dash.globalping.io, on the Tokens page, and sent as a Bearer token): 500 tests/hour, 500 probes per measurement. Use a token only if the user or the project's existing config provides one; otherwise work unauthenticated.
  • One server token means all the app's users share that token's hourly limit.
  • A test is one probe's run. A measurement with limit: 10 costs 10 tests.
  • Credits are spent automatically by authenticated users on tests above the hourly limit (1 credit per test).
  • Rate limit errors: a 429 means the hourly limit or credits are exhausted. Response headers show the remaining limit and reset time. Tell the user what happened and (where the app can) suggest signing in or using a token, getting credits, or using fewer probes. Don't retry in a tight loop.
  • Polling: after creating a measurement, poll GET /v1/measurements/{id} until the status is no longer in-progress. Wait 500 ms after each response (not on a fixed interval) and never poll faster. Use ETag/If-None-Match caching. Allow at least 10 seconds beyond the probe-side timeout (max 30 s) before giving up client-side.
  • Non-browser apps: set User-Agent and Accept-Encoding headers as described in the spec's general client guidelines.

5. Rules

Choosing sensible values

  • Start with a small limit. The default is 1. Increase it only when the feature needs a spread of locations.
  • Omit locations when the user doesn't care where the test runs. Without locations, the API uses the default world, which picks probes spread proportionally across continents.
  • Use magic locations for free-text input, combining filters with + (comcast+california) and listing several with commas (Berlin,South America). Use the structured location fields (see spec) for strict control or per-location limits; a global limit and per-location limits can't be combined.
  • For uptime checks, add datacenter-network (e.g. Germany+datacenter-network) to use probes on stable infrastructure, or eyeball-network to see what end users on ISP networks experience.
  • To compare things fairly (e.g., two targets, several test types), pass an earlier measurement's ID as locations (see section 2).
  • Set inProgressUpdates: true only for interactive UIs that show live progress, not for scripts/CI.
  • Don't re-run identical measurements needlessly (page loads, loops). Cache results where freshness allows.

Hard constraints

  • Never expose an API token (client code, repos, logs, errors). Call Globalping from a server and read the token from the environment/secret store. If the user pastes a token in chat, never write it into files or examples; recommend rotating it.
  • Never put secrets or personal data in targets, headers, or other measurement parameters (results are public).
  • Don't invent endpoints, parameters, option names, response fields, or limits. If it isn't in spec.yaml, the README, or the docs, it doesn't exist; ask the user.
  • Use only options valid for the chosen measurement type. The spec doesn't allow additional fields, so don't send extras.
  • Don't parse rawOutput; use the structured fields instead (it is meant for display).
  • Handle per-probe statuses (finished, failed, offline, in-progress), and handle zero/fewer results than requested and 422 (no matching probes) without crashing.
  • Don't over-build: implement only what the user asked for, and don't add features, dependencies, or infrastructure that weren't requested.

6. Known Pitfalls

  • If your web fetch tool can't read spec.yaml, download it with curl.

7. Verification Checklist

Before finishing, confirm:

  • Every field exists in the spec.
  • A real request was run against the live API.
  • Nothing secret in code, repo, or logs.
  • Errors and partial results are handled (per Rules).