API Documentation

Integrate TraceMapper into your applications with our REST API.

The API is included in the Pro and Business plans. Create your key in the dashboard, then send it in the Authorization header.

Authentication

All API requests require an API key sent in the Authorization header as a Bearer token. Keys passed in the query string are rejected. Generate your API key from the Dashboard.

Authorization header (recommended)

Authorization: Bearer tm_your_api_key

API keys expire after 1 year. You can regenerate them from the Dashboard.

Error Codes

Every endpoint answers errors as JSON with a stable error code. The message field, when present, is English and meant for your logs: branch on the code.

400Invalid parameter (INVALID_INPUT, INVALID_DESTINATION, INVALID_URL, PORT_NOT_ALLOWED...) or a destination that cannot be probed (UNRESOLVED_HOST, BLOCKED_TARGET for private and reserved addresses).

401No API key: API_KEY_MISSING, or API_KEY_IN_QUERY when the key was sent as ?key= in the URL, which is refused. Send the Authorization header.

403Key refused: API_KEY_INVALID (unknown key, or the account is not on a paid plan) or API_KEY_EXPIRED (generate a new one from the Dashboard).

429RATE_LIMITED; TOO_MANY_CONCURRENT on /trace while another trace from your account is still running; GLOBALPING_QUOTA when the hourly allowance of remote measurements (sources other than our own servers) is used up; PORT_DAILY_LIMIT on /port-check past 2,000 ports a day per account or 500 per destination (with scope and limit). Wait the number of seconds given in the Retry-After header.

502An upstream source answered nothing usable (a DNS resolver, a registry, RIPEstat): the error field carries its code (for DNS: ESERVFAIL, EREFUSED...). A failure on our side or upstream is not counted against your quota.

503A limitation on our side, not a problem with your input: this server has no route in the requested IP family (IPV6_UNSUPPORTED, IPV4_UNSUPPORTED), or a data source did not answer (OUTAGES_UNAVAILABLE, OUTAGES_UNCONFIGURED, SOURCES_UNAVAILABLE). A partial answer says so instead: in /bgp, prefixesUnavailable or neighboursUnavailable set to true and prefixCount null mean the count could not be read, not zero; in /whois, registryUnavailable.

Endpoints

GET/api/v1/trace

Run a traceroute to a destination and return all hops with geolocation, ASN, latency, jitter, and packet loss data.

Parameters

Parameter	Type	Required	Description
dest	string	required	Destination IP address or hostname
maxHops	integer	optional	Maximum number of hops (1-64, default: 30)
protocol	string	optional	Protocol: icmp, udp, or tcp (default: icmp)
source	string	optional	Measurement point: local (Falkenstein, default), paris (Gravelines) or a Globalping location id such as gp-uk. GET /api/v1/status lists them.

Example Response

{
  "dest": "8.8.8.8",
  "source": "local",
  "protocol": "icmp",
  "status": "completed",
  "address": "8.8.8.8",
  "totalHops": 12,
  "hops": [
    {
      "hopNumber": 1,
      "ip": "192.168.1.1",
      "hostname": "router.local",
      "asn": null,
      "asnOrg": null,
      "city": null,
      "country": null,
      "lat": null,
      "lon": null,
      "latencyAvg": 1.2,
      "latencyMin": 0.8,
      "latencyMax": 1.5,
      "jitter": 0.3,
      "packetLoss": 0.0,
      "isTimeout": false
    }
  ]
}

GET/api/v1/traces

List your saved traces with pagination. Supports filtering by destination.

Parameter	Type	Description
limit	integer	Results per page (1-100, default 20)
offset	integer	Number of results to skip (default 0)
dest	string	Filter by destination IP or hostname

GET/api/v1/status

Get API status, available sources, and rate limit info. No authentication required.

GET/api/v1/ping

Ping a host and return latency statistics, packet loss, and individual round-trip times.

Parameters

Parameter	Type	Required	Description
host	string	required	IP address or hostname to ping
count	integer	optional	Number of ping packets to send (1-20, default: 4)
family	string	optional	IP version: auto (default), 4 or 6. The response carries the family actually used.

Example Response

{
  "host": "8.8.8.8",
  "resolvedIp": "8.8.8.8",
  "count": 4,
  "sent": 4,
  "received": 4,
  "packetLoss": 0,
  "latency": {
    "min": 1.23,
    "avg": 2.45,
    "max": 3.67,
    "jitter": 0.89
  },
  "rtts": [1.23, 2.45, 3.67, 2.45],
  "family": 4
}

GET/api/v1/dns

Perform a DNS lookup for a domain and return the resolved records with query time.

Parameters

Parameter	Type	Required	Description
domain	string	required	Domain name to look up
type	string	optional	Record type: A, AAAA, CNAME, MX, NS, TXT, SOA, PTR, CAA or SRV (default: A). For PTR, domain may be an IP address.
resolver	string	optional	Resolver that answers: cloudflare (default), google, quad9, opendns or authoritative (the zone's own nameservers). The former value system is read as cloudflare. The response names the servers actually queried.

Example Response

{
  "domain": "example.com",
  "type": "A",
  "records": [
    { "address": "93.184.216.34", "ttl": 300 }
  ],
  "queryTime": 12.34,
  "server": "cloudflare",
  "servers": ["1.1.1.1", "1.0.0.1"]
}

GET/api/v1/http-check

Check an HTTP(S) URL and return status code, response time, redirect chain, headers, and SSL certificate details.

Parameters

Parameter	Type	Required	Description
url	string	required	URL to check (https:// is added if omitted). Ports 80, 443, 8080 and 8443 only: any other port answers 400 PORT_NOT_ALLOWED.

Example Response

{
  "url": "https://example.com",
  "reachable": true,
  "failure": null,
  "statusCode": 200,
  "statusText": "OK",
  "responseTime": 145,
  "redirects": [],
  "headers": {
    "content-type": "text/html; charset=UTF-8",
    "server": "nginx"
  },
  "ssl": {
    "valid": true,
    "problem": null,
    "problemCode": null,
    "issuer": "DigiCert Inc",
    "validFrom": "2026-01-01",
    "validTo": "2027-01-01",
    "daysRemaining": 180,
    "protocol": "TLSv1.3",
    "sans": ["example.com", "www.example.com"]
  },
  "security": {
    "grade": "B",
    "score": 75,
    "findings": [
      { "key": "strict-transport-security", "present": true,
        "value": "max-age=31536000", "status": "ok" },
      { "key": "content-security-policy", "present": false,
        "value": null, "status": "missing" }
    ]
  },
  "resolvedIp": "93.184.216.34",
  "family": 4
}

reachable is false when no HTTP response was obtained, and failure then gives a code and the reason. A certificate problem (expired, wrong hostname, incomplete chain) is an answer, not an error: the status is 200, with reachable: false, the certificate's code in failure and the certificate itself in ssl. security grades the security headers from A to F, one finding per header.

Certificate failure (HTTP 200)

{
  "url": "https://expired.example.com",
  "reachable": false,
  "failure": {
    "code": "CERT_HAS_EXPIRED",
    "message": "The certificate has expired."
  },
  "statusCode": null,
  "ssl": {
    "valid": false,
    "problemCode": "CERT_HAS_EXPIRED",
    "validTo": "2026-01-01",
    "daysRemaining": -267
  },
  "security": null
}

GET/api/v1/port-check

Check if a TCP port is open on a host and return the response time and service name.

Parameters

Parameter	Type	Required	Description
host	string	required	IP address or hostname to check
port	integer	optional	Port number to check (1-65535). Required unless ports=common is given.
ports	string	optional	Use "common" instead of port to scan the common ports (21, 22, 25, 53, 80, 443, ...). The response then carries a results array, one entry per port.
timeout	integer	optional	Connection timeout per port, in milliseconds (500-10000, default: 3000).

Example Response

{
  "host": "example.com",
  "resolvedIp": "93.184.216.34",
  "family": 4,
  "port": 443,
  "state": "open",
  "open": true,
  "responseTime": 23,
  "service": "HTTPS"
}

GET/api/v1/ip-reputation

Check an IP address reputation against DNS blacklists and AbuseIPDB, with geolocation data.

Each list that lists the address gives a kind: abuse (spam, infected machine, hijacked network) or policy. For Spamhaus ZEN, categories decodes the return codes (sbl, css, xbl, drop, pbl). A PBL listing (127.0.0.10 or 127.0.0.11) only marks an end-user connection: it is policy and does not count in the score.

Parameters

Parameter	Type	Required	Description
ip	string	required	IPv4 or IPv6 address to check

Example Response

{
  "ip": "8.8.8.8",
  "reputation": "clean",
  "score": 0,
  "listsAnswered": 5,
  "listsQueried": 5,
  "abuseipdb": {
    "status": "ok",
    "score": 0,
    "totalReports": 12,
    "lastReported": "2026-06-01T10:00:00Z"
  },
  "blacklists": [
    { "name": "Spamhaus ZEN", "status": "clean", "listed": false },
    { "name": "SpamCop", "status": "clean", "listed": false },
    { "name": "Barracuda", "status": "unavailable", "listed": false, "reason": "no_answer" }
  ],
  "geo": {
    "country": "US",
    "isp": "Google LLC",
    "org": "Google LLC",
    "as": "AS15169 Google LLC"
  }
}

GET/api/v1/whois

Registration data for a public IP address over RDAP: organisation, network range, country, abuse contact and reverse DNS name.

Parameters

Parameter	Type	Required	Description
ip	string	required	Public IPv4 or IPv6 address to look up

Example Response

{
  "ip": "8.8.8.8",
  "hostname": "dns.google",
  "org": "Google LLC",
  "netName": "GOGL",
  "netRange": "8.8.8.0/24",
  "country": "US",
  "countrySource": "geoip",
  "abuse": "network-abuse@google.com",
  "registry": "whois.arin.net",
  "registryUnavailable": false,
  "asn": "AS15169 Google LLC",
  "reserved": false
}

GET/api/v1/subdomains

List the names a domain has certified, read from the public Certificate Transparency logs. Answers carry the source that replied and whether the view is partial.

Parameters

Parameter	Type	Required	Description
domain	string	required	Registrable domain name to search (e.g. example.com)

Example Response

{
  "domain": "tracemapper.com",
  "source": "crtsh",
  "sources": [{ "id": "crtsh", "status": "ok" }],
  "partial": false,
  "subdomains": [
    {
      "name": "tracemapper.com",
      "firstSeen": "2026-08-07T00:00:00.000Z",
      "lastSeen": "2026-11-05T01:22:00.000Z",
      "certificates": 1,
      "wildcard": false
    }
  ],
  "certificates": [],
  "totals": { "subdomains": 3, "wildcards": 1, "certificates": 13 },
  "stale": false,
  "fetchedAt": "2026-09-11T07:20:00.000Z"
}

GET/api/v1/email-check

SPF, DKIM, DMARC and MX for a domain, interpreted. The spf.lookups field counts DNS-querying terms recursively through every include, which is the limit records silently cross.

Parameters

Parameter	Type	Required	Description
domain	string	required	Mail domain to check (e.g. example.com)
selectors	string	optional	Up to five DKIM selectors, comma separated. Omitted, the common ones are tried.

Example Response

{
  "domain": "example.com",
  "verdict": "warning",
  "spf": {
    "status": "warning",
    "record": "v=spf1 include:_spf.example.net ~all",
    "lookups": 9,
    "lookupLimit": 10,
    "truncated": false,
    "allQualifier": "~",
    "includes": [{ "domain": "_spf.example.net", "depth": 0, "cost": 9 }],
    "findings": [
      { "code": "spf_lookups_near_limit", "severity": "warning",
        "params": { "count": 9, "limit": 10 } }
    ]
  },
  "dmarc": { "status": "warning", "policy": "none", "rua": ["mailto:d@example.com"], "findings": [] },
  "dkim": { "status": "unknown", "found": [], "selectorsTried": ["default", "google"] },
  "mx": { "status": "ok", "hosts": [{ "host": "mx.example.com", "priority": 10, "resolves": true }] },
  "checkedAt": "2026-09-11T09:30:00.000Z"
}

GET/api/v1/outages

Internet outages and disruptions observed by Cloudflare Radar: affected countries and autonomous systems, declared cause, start and end. Filter by ASN to answer whether a network your traffic crosses is reporting a problem. Returns 503 with a status of unconfigured or unavailable when the feed itself could not answer, which is never the same as an empty list.

Parameters

Parameter	Type	Required	Description
range	string	optional	Period to look back over: 1d, 7d (default), 14d or 28d
asn	string	optional	Keep only the outages touching this autonomous system, e.g. 3215 or AS3215

Example Response

{
  "status": "ok",
  "events": [
    {
      "id": "1234",
      "locations": [{ "code": "IQ", "name": "Iraq" }],
      "networks": [{ "asn": 203214, "name": "HulumTele" }],
      "cause": "GOVERNMENT_DIRECTED",
      "outageType": "NATIONWIDE",
      "scope": null,
      "description": "Exam Shutdown",
      "startDate": "2026-09-10T03:30:00.000Z",
      "endDate": "2026-09-10T03:45:00.000Z",
      "ongoing": false,
      "linkedUrl": null
    }
  ],
  "totals": { "ongoing": 0, "ended": 5 },
  "dateRange": "7d",
  "stale": false,
  "fetchedAt": "2026-09-11T07:20:00.000Z"
}

GET/api/v1/bgp

Look up BGP routing information for an IP address, a prefix or an autonomous system. For an address or a prefix: announced prefix, origin ASN, AS paths, upstream providers and RPKI status. For an AS number: the prefixes it announces and its neighbours, in a different response shape.

Parameters

Parameter	Type	Required	Description
target	string	required	IP address, prefix (e.g. 8.8.8.0/24) or AS number (e.g. AS15169)

Response for an address or a prefix

{
  "kind": "prefix",
  "target": "8.8.8.8",
  "prefix": "8.8.8.0/24",
  "allocationBlock": "8.0.0.0/8",
  "announced": true,
  "origin": { "asn": 15169, "holder": "Google LLC" },
  "rpki": "valid",
  "paths": [
    {
      "collector": "rrc00",
      "peer": "80.249.208.1",
      "asPath": [13335, 15169],
      "asPathCollapsed": [13335, 15169],
      "communities": ["13335:10000"]
    }
  ],
  "pathCount": 245,
  "collectorCount": 24,
  "upstreamAsns": [
    { "asn": 13335, "holder": "Cloudflare Inc", "count": 45 }
  ]
}

Response for an AS number (target=AS15169)

{
  "kind": "asn",
  "target": "AS15169",
  "asn": 15169,
  "holder": "GOOGLE - Google LLC",
  "announced": true,
  "prefixCount": 1024,
  "prefixes": ["8.8.8.0/24", "8.8.4.0/24"],
  "prefixesTruncated": true,
  "prefixesUnavailable": false,
  "neighboursUnavailable": false,
  "neighbours": [
    { "asn": 3356, "holder": "LEVEL3", "relation": "upstream" },
    { "asn": 36040, "holder": "YOUTUBE", "relation": "downstream" }
  ]
}

Rate Limits

Every authenticated endpoint, /trace included, draws on one budget per API key: 60 requests per minute on the Pro plan and 300 per minute on the Business plan. Past it you receive a 429 with a Retry-After header. On top of that, one trace per account runs at a time, and /port-check opens at most 120 connections per minute per account (ports=common counts each port).

Code Examples

cURL

# With Authorization header
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/trace?dest=8.8.8.8"

# List saved traces
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/traces?limit=10"

# Ping
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/ping?host=8.8.8.8&count=4"

# DNS
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/dns?domain=_dmarc.example.com&type=TXT&resolver=authoritative"

# HTTP Check
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/http-check?url=https://example.com"

# Port Check
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/port-check?host=example.com&port=443"

# IP Reputation
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/ip-reputation?ip=8.8.8.8"

# BGP: an address, a prefix, or an AS number
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/bgp?target=AS15169"

# WHOIS / RDAP
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/whois?ip=8.8.8.8"

# Subdomains from the certificate transparency logs
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/subdomains?domain=example.com"

# Outages declared on one autonomous system
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/outages?range=7d&asn=AS3215"

# SPF, DKIM, DMARC and MX for a domain
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/email-check?domain=example.com&selectors=resend"

JavaScript / Node.js

const API_KEY = "tm_your_api_key";
const headers = { Authorization: `Bearer ${API_KEY}` };

// Traceroute
const trace = await fetch(
  "https://tracemapper.com/api/v1/trace?dest=8.8.8.8",
  { headers }
).then(r => r.json());
console.log(trace.hops);

// Ping
const ping = await fetch(
  "https://tracemapper.com/api/v1/ping?host=8.8.8.8",
  { headers }
).then(r => r.json());
console.log(ping.latency);

// DNS
const dns = await fetch(
  "https://tracemapper.com/api/v1/dns?domain=example.com&type=A",
  { headers }
).then(r => r.json());
console.log(dns.records);

Python

import requests

headers = {"Authorization": "Bearer tm_your_api_key"}

# Traceroute
r = requests.get(
    "https://tracemapper.com/api/v1/trace",
    params={"dest": "8.8.8.8"},
    headers=headers,
)
print(r.json()["hops"])

# Ping
r = requests.get(
    "https://tracemapper.com/api/v1/ping",
    params={"host": "8.8.8.8", "count": 4},
    headers=headers,
)
print(r.json()["latency"])

# DNS
r = requests.get(
    "https://tracemapper.com/api/v1/dns",
    params={"domain": "example.com", "type": "MX"},
    headers=headers,
)
print(r.json()["records"])