API Documentation

The BGPScout API allows you to query network data, retrieve ASN details, and submit traceroute results. All responses are JSON unless otherwise noted.

Base URL:https://bgpscout.io/api

Trace Processing Pipeline

Every traceroute submitted to BGPScout goes through a multi-stage enrichment pipeline before being included in any analysis or public results:

1. Submission — Raw MTR/traceroute data is received via the API or RIPE Atlas.
2. Enrichment — Each hop IP is resolved to an ASN (via BGP prefix tables), geolocated (via geofeed, IPinfo, MaxMind), and classified (anycast, IXP, cloud, etc.).
3. Quality Scoring — A 0-10 data quality score is computed based on: PTR record coverage, geo coverage, hop completion ratio, and path coherence.
4. Display Gating — Traces with quality score ≤ 2 are auto-rejected. Scores 3-5 go to pending review. Scores 6+ are auto-approved. Only approved traces appear in search results and analysis.

Boomerang Detection

A "boomerang route" is detected when a traceroute from country A to a destination also in country A transits through a different country. This indicates suboptimal routing where domestic traffic unnecessarily crosses international borders.

Data Sources

• Traceroutes — User-submitted MTR tests, RIPE Atlas measurements, automated probes in 30+ countries
• ASN Data — ARIN, RIPE NCC, APNIC, LACNIC, AFRINIC registry data
• PeeringDB — Facility presence, IXP memberships, port speeds
• GeoIP — Geofeed (RFC 8805), IPinfo, MaxMind, PTR hostname analysis
• Domain Intelligence — Certificate Transparency, DNS enumeration, WHOIS

Some endpoints require an API key passed via the X-API-Key HTTP header. Public endpoints do not require authentication.

To obtain an API key, log in and visit your Account Settings page.

curl -H "X-API-Key: your_api_key_here" \
     https://bgpscout.io/api/traceroutes/submit

All endpoints are rate-limited to 100 requests per hour per API key (or per IP for unauthenticated requests). Exceeding this limit returns a 429 response.

Returns aggregate statistics about all collected traceroutes.

Example Request

curl https://bgpscout.io/api/traceroutes/stats

Example Response

{
  "success": true,
  "stats": {
    "total_traces": 14523,
    "source_countries": 12,
    "unique_destinations": 987,
    "unique_source_asns": 45,
    "boomerang_count": 312,
    "leaves_country_count": 1804,
    "earliest_trace": "2025-01-15T00:00:00.000Z",
    "latest_trace": "2026-04-02T18:30:00.000Z"
  },
  "top_source_countries": [
    { "source_country": "CA", "trace_count": 9821 },
    { "source_country": "US", "trace_count": 3104 }
  ]
}

Submit one or more traceroute results for storage and analysis.

Headers

Request Body

{
  "traces": [
    {
      "host": "example.com",
      "dest_ip": "93.184.216.34",
      "source_ip": "192.168.1.1",
      "source_country": "CA",
      "platform": "linux",
      "tool": "mtr",
      "completed": true,
      "hops": [
        {
          "hop_number": 1,
          "ip": "192.168.1.1",
          "hostname": "gateway.local",
          "rtt_avg": 1.2,
          "rtt_min": 0.8,
          "rtt_max": 2.1,
          "loss_pct": 0
        },
        {
          "hop_number": 2,
          "ip": "10.0.0.1",
          "rtt_avg": 5.4
        }
      ]
    }
  ]
}

Hop Fields

Example Response

{
  "success": true,
  "trace_ids": [1042, 1043],
  "count": 2
}

Error Response

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "trace_index": 0, "errors": ["Invalid dest_ip format"] }
  ]
}

Returns detailed information about an ASN including peering quality and route scoring.

Parameters

Example Request

curl https://bgpscout.io/api/asn/577

Example Response

{
  "asn": 577,
  "name": "BACOM",
  "country": "CA",
  "rir": "arin",
  "traffic_level": "Medium",
  "network_type": "NSP",
  "on_ix": true,
  "peering_quality": {
    "crossing_rate": 0.12,
    "quality_tag": "Good"
  },
  "route_score": {
    "quality": 78.5,
    "route": 82.1,
    "overall": 80.3
  },
  "url": "https://bgpscout.io/asns/577"
}

Returns a self-contained HTML card for an ASN that can be embedded via an iframe.

Usage

<iframe src="https://bgpscout.io/api/embed/asn/577"
        width="320" height="200"
        frameborder="0"></iframe>

Preview

The widget displays the ASN name, country, peering quality badge, route score, and a link back to BGPScout.

BGPScout exposes an MCP server that lets AI assistants (Claude, ChatGPT, Cursor, etc.) query network data, look up ASNs, search traceroutes, and run analysis using natural language.

MCP Server URL

https://bgpscout.io/mcp

Authentication

The MCP server supports two authentication methods:

Claude Desktop / Cursor Setup

Add this to your MCP client configuration:

{
  "mcpServers": {
    "bgpscout": {
      "url": "https://bgpscout.io/mcp",
      "headers": {
        "X-API-Key": "your_api_key_here"
      }
    }
  }
}

Get your API key from Account Settings.

Available Tools

Once connected, the MCP server provides these tools:

Example Prompts

To connect BGPScout to ChatGPT as an MCP app:

1. Go to ChatGPT Settings > Apps > Add App
2. Set Name to bgpscout.io
3. Set MCP Server URL to:

   https://bgpscout.io/mcp

4. Set Authentication to OAuth
5. Click Advanced settings and set Registration method to User-Defined OAuth Client
6. Fill in the fields:

   OAuth Client ID	bgpscout-chatgpt
   OAuth Client Secret	Leave empty
   Token endpoint auth method	none
   Auth URL	https://bgpscout.io/oauth/authorize
   Token URL	https://bgpscout.io/oauth/token

7. Check "I understand and want to continue"
8. Click Create

OAuth Endpoints Reference