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)
| Field | Type | Description |
|---|---|---|
| typerequired | "mtr" | "ping" | "trace" | "dnst" | "dnsr" | "bgp" | Which test to run. |
| targetrequired | string | A hostname, IPv4 address or IPv6 address. |
| proberequired | string | A probe id from |
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/testResponse 200
| Field | Type | Description |
|---|---|---|
| id | string | Share id of the saved result. |
| type | "mtr" | "ping" | "trace" | "dnst" | "dnsr" | "bgp" | The test that ran. |
| target | string | The target as it was used, with spaces removed. |
| probe | string | The probe that ran it. |
| lines | array of string | The tool's output, one line per entry. |
| expires_at | date-time | When the saved result is deleted. |
| credits | TestCredits | Your daily allowance after this test. |
TestCredits
| Field | Type | Description |
|---|---|---|
| limit | integer | Your credits for today. It grows with each sponsored probe you have online. |
| used | integer | Credits used today. |
| remaining | integer | Credits left today. |
| free | boolean | True when this test was on your own probe and used no credit. |
| resets_at | date-time | When |
{
"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.