API Documentation

Integrate TraceMapper into your applications with our REST API. Available for Pro users.

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.

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
key	string	required	Your API key (starts with tm_)
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)

Example Response

{
  "dest": "8.8.8.8",
  "protocol": "icmp",
  "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
    }
  ]
}

Error Codes

401Missing or invalid API key

403Not a Pro user or invalid key

429Rate limit exceeded

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)

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]
}

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, MX, NS, CNAME, TXT, or SOA (default: A)

Example Response

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

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)

Example Response

{
  "url": "https://example.com",
  "statusCode": 200,
  "statusText": "OK",
  "responseTime": 145,
  "redirects": [],
  "headers": {
    "content-type": "text/html; charset=UTF-8",
    "server": "nginx"
  },
  "ssl": {
    "valid": true,
    "issuer": "DigiCert Inc",
    "validFrom": "2024-01-01",
    "validTo": "2025-01-01",
    "daysRemaining": 180,
    "protocol": "TLSv1.3",
    "sans": ["example.com", "www.example.com"]
  }
}

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	required	Port number to check (1-65535)
ports	string	optional	Use "common" to scan common ports (21, 22, 25, 53, 80, 443, ...)

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.

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": null,
  "registry": "whois.arin.net",
  "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 or prefix, including origin ASN, AS paths, and upstream providers.

Parameters

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

Example Response

{
  "prefix": "8.8.8.0/24",
  "origin": { "asn": 15169, "holder": "Google LLC" },
  "paths": [
    {
      "collector": "rrc00",
      "asPath": [13335, 15169],
      "communities": ["13335:10000"]
    }
  ],
  "pathCount": 245,
  "collectorCount": 24,
  "upstreamAsns": [
    { "asn": 13335, "holder": "Cloudflare Inc", "count": 45 }
  ]
}

Rate Limits

API requests are limited to 60 requests per minute per API key on the Pro plan and 300 per minute on the Business plan. If you exceed this limit, you will receive a 429 status code with a Retry-After header.

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"])