API

Run tests from probes around the world and read saved results, over plain HTTPS and JSON. Everything here is also described in an OpenAPI 3.1 document you can load into a client generator or an API tool.

Base URL
https://api.mtr.tools
Specification
/openapi.json (OpenAPI 3.1)

Authentication

Endpoints marked Needs a token take a personal API token. Create one under Account, API tokens and send it as a bearer token:

curl -H "Authorization: Bearer $MTR_TOKEN" \
  https://api.mtr.tools/account/credits

Tokens are created on the website only: there is no API call that makes one, so a token can never be used to mint more. A token is shown once, when it is created, and stored only as a hash. An account can hold a limited number at a time; revoke one to free a slot. Public read endpoints need no token at all.

Errors

Errors use ordinary HTTP status codes. The body is a short plain-text message, not JSON, and is empty for a 401 or 403. Check the status code first.

  • 400The request is malformed: a bad target, an unknown test type, a value out of range.
  • 401No token, or one that is wrong or has been revoked.
  • 403The account is banned or has had API access switched off.
  • 404Nothing with that id, or it has expired.
  • 409The request conflicts with the current state, for example a probe that is not live.
  • 429A limit was reached. See Limits below.
  • 502The probe could not be reached.

Limits

Each account has a daily allowance of test credits, and every sponsored probe you have online adds to it: the more of the network you carry, the more you may use. Running a test with POST /api/teston someone else's probe uses one. Tests on your own probes, ones you submitted or on an AS number you operate, are free and do not count. When the allowance is used up, POST /api/test answers 429 until it resets at midnight UTC.

Every /api/test response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (the Unix time of the reset), and the same numbers are at GET /account/credits, along with resets_at and how your limit is made up.

The public read endpoints are limited per IP address over a short window. A 429 from one of those means slow down and retry a moment later.

Test types

The typeof a test is one of these. Not every probe supports every type: check a probe's caps in /probes.json.

mtr
Traceroute and ping combined: every hop, with loss and latency.
ping
ICMP echo to the target.
trace
Traceroute to the target.
dnst
Follows DNS delegation for a name from the root down.
dnsr
Resolves a name using the probe's resolver.
bgp
The route the probe's network has for the target.

Tests

Run a measurement from a probe.

Run a test from a probe

post/api/testNeeds a token

Runs one measurement and waits for it to finish, then returns the tool's output lines. The result is also saved, and id can be opened at /r/{id} on the website or fetched from /results/{id}.

A test on a probe that is not yours uses one daily credit. Tests on your own probes, ones you submitted or on an AS number you operate, are free.

Request body (JSON)

FieldTypeDescription
typerequired"mtr" | "ping" | "trace" | "dnst" | "dnsr" | "bgp"

Which test to run. dnst traces DNS delegation, dnsr resolves a name, bgp looks up the route. Not every probe supports every type: see caps in /probes.json. Anything else is refused.

targetrequiredstring

A hostname, IPv4 address or IPv6 address.

proberequiredstring

A probe id from /probes.json or /probes/mine.

Try it

curl \
  -X POST \
  -H "Authorization: Bearer $MTR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"ping","target":"1.1.1.1","probe":"14bcf6d"}' \
  https://api.mtr.tools/api/test

Response 200

FieldTypeDescription
idstring

Share id of the saved result.

type"mtr" | "ping" | "trace" | "dnst" | "dnsr" | "bgp"

The test that ran.

targetstring

The target as it was used, with spaces removed.

probestring

The probe that ran it.

linesarray of string

The tool's output, one line per entry.

expires_atdate-time

When the saved result is deleted.

creditsTestCredits

Your daily allowance after this test.

TestCredits

FieldTypeDescription
limitinteger

Your credits for today. It grows with each sponsored probe you have online.

usedinteger

Credits used today.

remaininginteger

Credits left today.

freeboolean

True when this test was on your own probe and used no credit.

resets_atdate-time

When used goes back to zero: the next midnight UTC.

{
  "id": "Zq3v0n1mXk8Yb2Lr5tHw9A",
  "type": "ping",
  "target": "1.1.1.1",
  "probe": "14bcf6d",
  "lines": [
    "PING 1.1.1.1 (1.1.1.1) 56(84) bytes of data.",
    "64 bytes from 1.1.1.1: icmp_seq=1 ttl=58 time=1.12 ms"
  ],
  "expires_at": "2026-12-15T03:10:00+00:00",
  "credits": {
    "limit": 50,
    "used": 1,
    "remaining": 49,
    "free": false,
    "resets_at": "2026-11-16T00:00:00Z"
  }
}

Status codes

  • 200The test finished.
  • 400The target is not a valid hostname or IP, or the test type is unknown.
  • 401The token is missing, wrong or revoked. The body is empty.
  • 403The account is banned or has had API access switched off. The body is empty.
  • 404There is no probe with that id.
  • 409The probe exists but is not live.
  • 429Your daily credits are used up. Tests on your own probes still work.
  • 502The probe could not be reached.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

Probes

The probes you can test from.

List live probes

get/probes.jsonNo token needed

Every probe that can currently run tests, grouped by region. Use a probe's id as probe in /api/test.

Try it

curl \
  https://api.mtr.tools/probes.json

Response 200

FieldTypeDescription
namestring

Region name, for example Europe.

serversarray of Probe

The probes in that region.

Probe

FieldTypeDescription
idstring

Probe id. Pass it as probe to /api/test.

countrystring

Country as its sponsor wrote it: a name or a two-letter code.

country_codestring

ISO 3166-1 alpha-2 country code, for example GB. Empty if not known.

citystring

City.

providerstring

The network that sponsors the probe.

asnumberinteger

AS number the probe sits on.

residentialboolean

True for a probe on a home connection.

sponsoredboolean

False for a probe mtr.tools runs itself rather than one a sponsor provides.

capsProbeCaps

What the probe can do. A flag that is missing or false means not supported.

statusboolean

True when the probe is reachable.

providerurlstring

The sponsor's website.

latitudenumber or null

Approximate latitude.

longitudenumber or null

Approximate longitude.

ProbeCaps

FieldTypeDescription
mtrboolean

Can run mtr.

pingboolean

Can run ping.

traceboolean

Can run trace.

dnstboolean

Can run dnst.

dnsrboolean

Can run dnsr.

bgpboolean

Can run bgp.

ipv4boolean

Has working IPv4.

ipv6boolean

Has working IPv6.

[
  {
    "name": "Europe",
    "servers": [
      {
        "id": "14bcf6d",
        "country": "United Kingdom",
        "country_code": "GB",
        "city": "London",
        "provider": "Mythic Beasts",
        "asnumber": 44684,
        "residential": false,
        "caps": {
          "ping": true,
          "mtr": true,
          "trace": true,
          "dnst": true,
          "bgp": false,
          "ipv4": true,
          "ipv6": true
        },
        "status": true,
        "providerurl": "https://www.mythic-beasts.com",
        "latitude": 51.5,
        "longitude": -0.12
      }
    ]
  }
]

Status codes

  • 200Probes grouped by region, largest group first.
  • 429Too many requests from your address in a short time. Wait a moment and retry.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

List your probes

get/probes/mineNeeds a token

Probes you submitted, plus every probe on an AS number you operate according to PeeringDB. Includes ones that are pending or rejected.

Try it

curl \
  -H "Authorization: Bearer $MTR_TOKEN" \
  https://api.mtr.tools/probes/mine

Response 200

FieldTypeDescription
idstring

Probe id.

countrystring

Country as its sponsor wrote it: a name or a two-letter code.

country_codestring

ISO 3166-1 alpha-2 country code, for example GB. Empty if not known.

citystring

City.

providerstring

Sponsor name.

asnumberinteger

AS number.

providerurlstring

Sponsor website.

latitudenumber or null

Approximate latitude.

longitudenumber or null

Approximate longitude.

status"pending" | "approved" | "live" | "rejected"

Where the probe is in review.

submitted_atdate-time or null

When it was submitted.

reviewed_atdate-time or null

When an admin reviewed it.

reject_reasonstring or null

Why it was rejected, if it was.

transport"ssh" | "agent"

How we reach the probe.

connectedboolean

For an agent probe, whether the agent is connected right now.

last_connected_atdate-time or null

When an agent last connected, or null if it never has.

sponsoredboolean

False for a probe mtr.tools runs itself rather than one a sponsor provides.

uptime_30dnumber or null

Percent of the last 30 days the probe was reachable, to one decimal. Null until there is some history.

Status codes

  • 200Your probes, newest first.
  • 401The token is missing, wrong or revoked. The body is empty.
  • 403The account is banned or has had API access switched off. The body is empty.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

Get a probe's history

get/probes/{id}/historyNeeds a token

What has happened to one of your probes, newest first: when it was submitted, approved, edited or removed, and by whom. For probes you submitted and probes on an AS number you operate. At most 100 entries.

Path parameters

  • id string. The probe id, from `/probes/mine`.

Try it

curl \
  -H "Authorization: Bearer $MTR_TOKEN" \
  https://api.mtr.tools/probes/14bcf6d/history

Response 200

FieldTypeDescription
idinteger

Entry id.

probe_idstring

The probe.

probe_labelstring

The probe as it was named at the time: place, then sponsor.

actor_user_idinteger or null

The account that did it, or null when mtr.tools did it automatically.

actor_namestring

That account's name at the time. Empty for an automatic action.

actionstring

What happened: submitted, approved, went_live, rejected, edited, edit_requested, removal_requested, request_dismissed, removed, key_issued or key_revoked. New kinds may be added.

detailobject

Extra facts about the action, such as the fields an edit changed or the reason given. Its keys depend on the action.

created_atdate-time

When it happened.

Status codes

  • 200The probe's history.
  • 401The token is missing, wrong or revoked. The body is empty.
  • 403The account is banned or has had API access switched off. The body is empty.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

Results

Saved results and shared links.

Get a saved result

get/results/{id}No token needed

One saved test result, by its share id. Results expire; an expired or unknown id is a 404.

Path parameters

  • id string. The share id from the link, 22 characters.

Try it

curl \
  https://api.mtr.tools/results/Zq3v0n1mXk8Yb2Lr5tHw9A

Response 200

FieldTypeDescription
idstring

Share id.

test_typestring

The test that ran.

targetstring

What was tested.

probe_idstring

The probe that ran it.

probe_metaProbeMeta

The probe's details as they were when the test ran.

raw_linesarray of string

The output. Usually an array of text lines. For tests the server could parse, an object instead: format names the layout (structured-v1) and result holds the parsed measurement.

created_atdate-time

When it ran.

expires_atdate-time

When it is deleted.

ProbeMeta

FieldTypeDescription
countrystring

Country.

country_codestring

ISO 3166-1 alpha-2 country code, for example GB. Missing on results saved before this field existed.

citystring

City.

providerstring

Sponsor name.

asnumberinteger

AS number.

{
  "id": "Zq3v0n1mXk8Yb2Lr5tHw9A",
  "test_type": "ping",
  "target": "1.1.1.1",
  "probe_id": "14bcf6d",
  "probe_meta": {
    "country": "DE",
    "city": "Frankfurt",
    "provider": "Example Networks",
    "asnumber": 64500
  },
  "raw_lines": [
    "PING 1.1.1.1 (1.1.1.1) 56(84) bytes of data.",
    "64 bytes from 1.1.1.1: icmp_seq=1 ttl=58 time=1.12 ms"
  ],
  "created_at": "2026-11-15T03:10:00Z",
  "expires_at": "2026-12-15T03:10:00Z"
}

Status codes

  • 200The saved result.
  • 404Nothing with that id, or it has expired.
  • 429Too many requests from your address in a short time. Wait a moment and retry.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

List your saved results

get/results/mineNeeds a token

Results from tests you ran while signed in or with your token, newest first. Summaries only: fetch /results/{id} for the output.

Try it

curl \
  -H "Authorization: Bearer $MTR_TOKEN" \
  https://api.mtr.tools/results/mine

Response 200

FieldTypeDescription
idstring

Share id.

test_typestring

The test that ran, for example ping.

targetstring

What was tested.

probe_idstring

The probe that ran it.

probe_metaProbeMeta

The probe's details as they were when the test ran.

created_atdate-time

When it ran.

expires_atdate-time

When it is deleted.

ProbeMeta

FieldTypeDescription
countrystring

Country.

country_codestring

ISO 3166-1 alpha-2 country code, for example GB. Missing on results saved before this field existed.

citystring

City.

providerstring

Sponsor name.

asnumberinteger

AS number.

Status codes

  • 200Your unexpired results.
  • 401The token is missing, wrong or revoked. The body is empty.
  • 403The account is banned or has had API access switched off. The body is empty.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

Get a bundle of results

get/bundles/{id}No token needed

Several results shared as one link (/b/{id} on the website).

Path parameters

  • id string. The share id from the link, 22 characters.

Try it

curl \
  https://api.mtr.tools/bundles/Zq3v0n1mXk8Yb2Lr5tHw9A

Response 200

FieldTypeDescription
idstring

Share id of the bundle.

created_atdate-time

When it was created.

expires_atdate-time

When it is deleted.

resultsarray of Result

The results in the bundle.

Result

FieldTypeDescription
idstring

Share id.

test_typestring

The test that ran.

targetstring

What was tested.

probe_idstring

The probe that ran it.

probe_metaProbeMeta

The probe's details as they were when the test ran.

raw_linesarray of string

The output. Usually an array of text lines. For tests the server could parse, an object instead: format names the layout (structured-v1) and result holds the parsed measurement.

created_atdate-time

When it ran.

expires_atdate-time

When it is deleted.

ProbeMeta

FieldTypeDescription
countrystring

Country.

country_codestring

ISO 3166-1 alpha-2 country code, for example GB. Missing on results saved before this field existed.

citystring

City.

providerstring

Sponsor name.

asnumberinteger

AS number.

Status codes

  • 200The bundle and its results.
  • 404Nothing with that id, or it has expired.
  • 429Too many requests from your address in a short time. Wait a moment and retry.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

Account

Your API tokens and daily credits.

Get your daily credits

get/account/creditsNeeds a token

How many test credits you have used today, when they reset, and how many API tokens your account may hold. Your daily limit is base plus per_probe for each sponsored probe you have online right now, so it can change during the day.

Try it

curl \
  -H "Authorization: Bearer $MTR_TOKEN" \
  https://api.mtr.tools/account/credits

Response 200

FieldTypeDescription
limitinteger

Test credits per day.

usedinteger

Credits used today.

remaininginteger

Credits left today.

baseinteger

The daily credits every account gets.

per_probeinteger

Extra daily credits for each sponsored probe you have online.

online_probesinteger

How many of your sponsored probes are online right now: live probes you own or that sit on a network you run.

resets_atdate-time

When used goes back to zero: the next midnight UTC.

max_tokensinteger

Most API tokens an account may hold at once.

unlimited_tokensboolean

True when the limits have been lifted for this account: it may hold any number of tokens and its tests use no credits.

{
  "limit": 100,
  "used": 1,
  "remaining": 99,
  "base": 50,
  "per_probe": 25,
  "online_probes": 2,
  "resets_at": "2026-11-16T00:00:00Z",
  "max_tokens": 10,
  "unlimited_tokens": false
}

Status codes

  • 200Your allowance.
  • 401The token is missing, wrong or revoked. The body is empty.
  • 403The account is banned or has had API access switched off. The body is empty.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

List your recent API calls

get/account/api-usageNeeds a token

The last 100 requests made with your tokens, newest first: what was called, with which token, and how it went. Entries are kept for 90 days. This request is itself logged.

Try it

curl \
  -H "Authorization: Bearer $MTR_TOKEN" \
  https://api.mtr.tools/account/api-usage

Response 200

FieldTypeDescription
idinteger

Entry id.

user_idinteger

Your account id.

user_namestring

Your account name.

token_idinteger or null

The token used. Still set after that token is revoked.

token_namestring

The token's label when the call was made.

methodstring

HTTP method.

pathstring

The path that was called, without its query string.

statusinteger

The HTTP status we answered with.

duration_msinteger

How long the request took, in milliseconds.

test_typestring or null

For /api/test, the test that was asked for.

targetstring or null

For /api/test, the target.

probe_idstring or null

For /api/test, the probe.

created_atdate-time

When the call was made.

[
  {
    "id": 9041,
    "user_id": 7,
    "user_name": "Ada",
    "token_id": 42,
    "token_name": "ci-server",
    "method": "POST",
    "path": "/api/test",
    "status": 200,
    "duration_ms": 2310,
    "test_type": "ping",
    "target": "1.1.1.1",
    "probe_id": "14bcf6d",
    "created_at": "2026-11-15T10:00:00Z"
  }
]

Status codes

  • 200Your recent calls.
  • 401The token is missing, wrong or revoked. The body is empty.
  • 403The account is banned or has had API access switched off. The body is empty.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.

List your API tokens

get/account/tokensNeeds a token

Your tokens, newest first. The token itself is never returned after creation, only its first 12 characters. Tokens are created and revoked on the website only, under Account, API tokens: there are no endpoints for either.

Try it

curl \
  -H "Authorization: Bearer $MTR_TOKEN" \
  https://api.mtr.tools/account/tokens

Response 200

FieldTypeDescription
idinteger

Token id, used to revoke it.

namestring

The label you gave it.

prefixstring

The first 12 characters of the token, to tell them apart.

created_atdate-time

When it was created.

last_used_atdate-time or null

When it was last used, or null if never.

Status codes

  • 200Your tokens.
  • 401The token is missing, wrong or revoked. The body is empty.
  • 403The account is banned or has had API access switched off. The body is empty.
  • 503mtr.tools is down for maintenance, or this feature is switched off for now. Nothing is wrong with your request: wait and retry.
MTR.tools - Copyright 2022 - 2026
Operated byParadox Networks
IssuesAPI