GnistAI GnistAI
Log in

Getting Started with IODA (Internet Outage Detection)

Internet outage detection and analysis — real-time alerts, processed events, aggregated summaries, and time-series signal data for countries, ASNs, and regions. Monitors BGP, active probing, and traffic data.

All Tutorials   |   Overview   |   Playground   |   MCP   |   REST API   |   Home
Security

Data source: IODA (Georgia Tech Internet Intelligence Lab)

Overview

IODA (Internet Outage Detection) wraps IODA (Georgia Tech Internet Intelligence Lab), handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

  1. Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
  2. Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config 
{
  "mcpServers": {
    "gnist-ioda": {
      "url": "https://context.gnist.ai/mcp/ioda/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

get_outage_alerts

Get recent internet outage alerts from IODA (Georgia Tech). Returns alerts about detected internet connectivity disruptions worldwide. Monitors BGP routing, active probing, and traffic data to detect outages affecting countries, autonomous systems (ASNs), and regions. Args: country_code: ISO 3166-1 alpha-2 country code to filter by (e.g. "US", "DE", "NO"). asn: Autonomous System Number to filter by (e.g. "15169" for Google). hours: Lookback window in hours (1-720, default 24). limit: Maximum results to return (1-200, default 20). Returns: Dict with 'source', 'count', and 'alerts' list. Each alert includes entity info, datasource, severity level, timestamp, and signal values.

ParameterTypeRequiredDescription
country_codeanyoptionalISO 3166-1 alpha-2 country code to filter by (e.g. "US", "DE", "NO").
asnanyoptionalAutonomous System Number to filter by (e.g. "15169" for Google, "13335" for Cloudflare).
hoursnumberoptionalLookback window in hours (1-720, default 24). (default: 24)
limitintegeroptionalMaximum results to return (1-200, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/ioda/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_outage_alerts", "arguments": {"country_code": "US"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/ioda/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'country_code': 'US'}, 'name': 'get_outage_alerts'}},
)
print(resp.json())

get_outage_events

Get processed internet outage events with severity and duration. Unlike raw alerts, events are correlated and processed to show distinct outage incidents with start/end times, severity scores, and affected datasources. Use this for a cleaner view of actual outage incidents. Args: country_code: ISO 3166-1 alpha-2 country code to filter by (e.g. "US", "DE", "NO"). asn: Autonomous System Number to filter by (e.g. "15169" for Google). hours: Lookback window in hours (1-720, default 24). limit: Maximum results to return (1-200, default 20). Returns: Dict with 'source', 'count', and 'events' list. Each event includes entity info, start/end times, severity score, and contributing datasources.

ParameterTypeRequiredDescription
country_codeanyoptionalISO 3166-1 alpha-2 country code to filter by (e.g. "US", "DE", "NO").
asnanyoptionalAutonomous System Number to filter by (e.g. "15169" for Google).
hoursnumberoptionalLookback window in hours (1-720, default 24). (default: 24)
limitintegeroptionalMaximum results to return (1-200, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/ioda/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_outage_events", "arguments": {"country_code": "US"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/ioda/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'country_code': 'US'}, 'name': 'get_outage_events'}},
)
print(resp.json())

get_outage_summary

Get aggregated outage summaries showing which entities had the most disruptions. Provides a high-level overview of outage activity, ranked by severity. Useful for identifying the most impacted countries, ASNs, or regions in a given time window. Args: country_code: ISO 3166-1 alpha-2 country code to filter by (e.g. "US", "DE", "NO"). hours: Lookback window in hours (1-720, default 24). limit: Maximum results to return (1-200, default 20). Returns: Dict with 'source', 'count', and 'summaries' list. Each summary includes entity info, aggregate score, outage count, and contributing datasources.

ParameterTypeRequiredDescription
country_codeanyoptionalISO 3166-1 alpha-2 country code to filter by (e.g. "US", "DE", "NO").
hoursnumberoptionalLookback window in hours (1-720, default 24). (default: 24)
limitintegeroptionalMaximum results to return (1-200, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/ioda/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_outage_summary", "arguments": {"country_code": "US"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/ioda/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'country_code': 'US'}, 'name': 'get_outage_summary'}},
)
print(resp.json())

get_signals

Get raw time-series signal data for a specific internet entity. Returns the actual measurement values over time for a given entity and datasource. Useful for visualizing connectivity trends, detecting drops, and analyzing the magnitude of outages. Args: entity_type: Entity type: "country", "asn", "region", or "county". entity_code: Entity code (e.g. "US" for country, "15169" for ASN). hours: Lookback window in hours (1-720, default 24). datasource: Data source: "bgp", "ucsd-nt", "merit-nt", "gtr", or "ping-slash24". max_points: Maximum data points in the time series (1-5000, default 500). Returns: Dict with 'source' and 'signal' containing the time-series data including datasource, entity info, time range, step size, and values array.

ParameterTypeRequiredDescription
entity_typestringrequiredEntity type: "country", "asn", "region", or "county".
entity_codestringrequiredEntity code (e.g. "US" for country, "15169" for ASN).
hoursnumberoptionalLookback window in hours (1-720, default 24). (default: 24)
datasourcestringoptionalData source: "bgp", "ucsd-nt", "merit-nt", "gtr", or "ping-slash24" (default "bgp"). (default: bgp)
max_pointsintegeroptionalMaximum data points in the time series (1-5000, default 500). (default: 500)
curl -X POST "https://context.gnist.ai/mcp/ioda/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_signals", "arguments": {"entity_type": "example", "entity_code": "US"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/ioda/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'entity_code': 'US', 'entity_type': 'example'},
            'name': 'get_signals'}},
)
print(resp.json())

search_entities

Search for internet entities (countries, ASNs, regions) in IODA's database. Find entity codes needed for other IODA tools. For example, search for "Google" to find its ASN (15169), or "Norway" to find its country code. Args: query: Search term (e.g. "United States", "Google", "Cloudflare"). entity_type: Filter by entity type: "country", "asn", "region", or "county". limit: Maximum results to return (1-200, default 20). Returns: Dict with 'source', 'count', and 'entities' list. Each entity includes type, code, name, and additional attributes.

ParameterTypeRequiredDescription
querystringrequiredSearch term (e.g. "United States", "Google", "Cloudflare").
entity_typeanyoptionalFilter by entity type: "country", "asn", "region", or "county".
limitintegeroptionalMaximum results to return (1-200, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/ioda/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_entities", "arguments": {"query": "United States"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/ioda/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'United States'}, 'name': 'search_entities'}},
)
print(resp.json())

report_feedback

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

ParameterTypeRequiredDescription
feedbackstringrequired
feedback_typestringoptional (default: general)
curl -X POST "https://context.gnist.ai/mcp/ioda/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/ioda/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_entities to find items, then get_outage_alerts to get full details. This two-step pattern is common for exploring data before drilling down.
Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does IODA (Internet Outage Detection) provide?

Internet outage detection and analysis — real-time alerts, processed events, aggregated summaries, and time-series signal data for countries, ASNs, and regions. Monitors BGP, active probing, and traffic data. It exposes 6 tools: get_outage_alerts, get_outage_events, get_outage_summary, get_signals, search_entities, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the IODA (Internet Outage Detection) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground
Try tools in your browser — no setup required.
Full Reference
Complete docs for all 6 tools.

Related Tutorials

NVD (National Vulnerability Database)
Tutorial
Cyber Intelligence
Tutorial