ioda-outages-mcp-server
An MCP server that investigates internet outages using IODA data. It provides tools to search for entities like countries and ASNs, check recent detection evidence and measurement coverage, retrieve overlapping outage events, rank entities by outage scores, fetch connectivity signals (BGP, ping, Merit), and retrieve detection alerts.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://ioda-outages.caseyjhand.com/mcpWhat you can do with it
- Resolve country, region, or ASN names and codes for outage investigations
- Inspect recent IODA detection evidence and measurement coverage for an entity
- Retrieve overlapping outage events for a specific entity or globally
- Fetch BGP, ping, or Merit telescope connectivity signals
Source and maintenance
Community listingRegistry 0.3.0
- Maintenance checked
Protocol and capabilities
- Server
- ioda-outages-mcp-server 0.3.1
- MCP protocol
- 2025-06-18
- Tools
- 6 advertised
- Resources
- 1 advertised
- Resource templates
- 1 advertised
- Prompts
- 0 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
6 advertised
ioda_search_entities — Ioda Search Entities
Advertised read-onlyOpen-world
Resolve country, region, autonomous-system, or geoasn (one ASN within a region or country) names and codes for outage investigations. Choose entityType and either query or entityCode; omit both to list the type. Countries use two letters, regions numeric IODA codes, ASNs decimal digits (AS prefix accepted), geoasns an ASN and a region or country code (40934-576, 59962-IR). Add relatedToType and relatedToCode to list entityType entities within one country, region, ASN, or geoasn, such as the regions or networks of a country; a scope combines with query. Region results can include IODA geolocation catch-alls named [Invalid Region (N)] or Unknown Region in <country>, which are not provinces or states; a notice names them. Metadata does not establish measurement coverage. Pages are zero-based; keep limit fixed when continuing.
ioda_search_entities input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"entityType"
],
"properties": {
"page": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page; restart at 0 when changing limit."
},
"limit": {
"type": "integer",
"default": 20,
"minimum": 1,
"multipleOf": 1,
"description": "Default 20; a larger value returns at most 1000 and says so. Keep fixed when continuing."
},
"query": {
"type": "string",
"pattern": "^(?:\\s*|\\s*\\S(?:[\\s\\S]{0,198}\\S)?\\s*)$(?![\\s\\S])",
"description": "Case-insensitive name substring, matched literally (% and _ are not wildcards); trimmed to at most 200 UTF-16 code units, and blank is omitted. Mutually exclusive with entityCode."
},
"entityCode": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Two-letter country code, IODA numeric region code, decimal ASN (AS prefix accepted), or geoasn code joining an ASN and a region or country code (40934-576, 59962-IR); resolve names with ioda_search_entities and pass a returned code here."
},
"entityType": {
"type": "string",
"pattern": "^(?:\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "country, region, asn, or geoasn (one ASN within a region or country); whitespace and case are normalized."
},
"relatedToCode": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Scope entity code, normalized like entityCode for relatedToType (IR, 1829, AS42337, 60627-IR); resolve names with ioda_search_entities. Provide with relatedToType."
},
"relatedToType": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "Scope type: country, region, asn, or geoasn. With relatedToCode, returns entityType entities related to that entity, such as the regions or networks of one country. Requires entityType and excludes entityCode; blank is omitted. Outage membership coverage is unverified independently of row pagination; page ioda_search_entities and query selected codes individually."
}
},
"additionalProperties": false
}ioda_search_entities output schema
{
"type": "object",
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
},
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"entities",
"pagination",
"provenance",
"applied"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_entity",
"conflicting_search",
"invalid_scope",
"upstream_bad_request",
"upstream_unprocessable",
"entity_not_found",
"upstream_rate_limited",
"upstream_queue_full",
"upstream_schema"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_entity`: entityCode is incompatible with entityType, zero or out of range. `conflicting_search`: Both query and entityCode were provided. `invalid_scope`: relatedToType and relatedToCode are incomplete or incompatible, the code is zero or out of range, or a scope comes with entityCode. `upstream_bad_request`: IODA rejects the request with HTTP 400 or an error envelope. `upstream_unprocessable`: IODA rejects the request with HTTP 422. `entity_not_found`: IODA returns an explicit entity 404. `upstream_rate_limited`: IODA returns HTTP 429. `upstream_queue_full`: The shared request queue is full. `upstream_schema`: IODA data or bucket metadata does not validate, or the response body is over 4 MiB. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Result interpretation and concrete next call."
},
"applied": {
"type": "object",
"description": "Every normalized input, effective window, filter and pagination value.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
},
"entities": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Source entity code"
},
"name": {
"type": "string",
"description": "Source entity name"
},
"type": {
"type": [
"string",
"null"
],
"description": "Source entity type, if reported"
},
"attrs": {
"type": "object",
"description": "Source attributes, preserved verbatim",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"subnames": {
"$ref": "#/$defs/__schema0",
"description": "Additional source names, preserved verbatim: usually a list; geoasn search rows carry named parts such as asn and region or country"
}
},
"description": "Entity metadata with unmodified source attributes",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "Original entity metadata; not measurement coverage."
},
"truncated": {
"type": "object",
"required": [
"shown",
"cap"
],
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page capacity",
"exclusiveMinimum": 0
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned records"
}
},
"description": "A full page may have further records; not an exact total.",
"additionalProperties": false
},
"pagination": {
"type": "object",
"required": [
"page",
"limit",
"returned",
"more"
],
"properties": {
"more": {
"enum": [
"possible",
"no"
],
"type": "string",
"description": "Whether another row page may exist; no does not verify related-scope membership coverage"
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page size",
"exclusiveMinimum": 0
},
"nextPage": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Next page when another may exist and IODA can continue the request; absent from a full page it cannot continue, whose notice names the route to the rest"
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned record count"
}
},
"description": "Upstream page and possible continuation.",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"endpoint",
"fetchedAt"
],
"properties": {
"endpoint": {
"type": "string",
"pattern": "^https:\\/\\/api\\.ioda\\.inetintel\\.cc\\.gatech\\.edu\\/v2\\/(?:entities\\/query|outages\\/(?:events|alerts|summary)|signals\\/raw\\/(?:country|region|asn|geoasn)\\/[^\\s/?#]+)$",
"description": "Fixed HTTPS IODA upstream endpoint URL"
},
"copyright": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source attribution"
},
"fetchedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "Fetch completion time UTC"
},
"requestTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source request time"
},
"responseTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source response time"
}
},
"description": "Endpoint and original source attribution.",
"additionalProperties": false
}
},
"additionalProperties": false
}ioda_search_entities annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ioda_get_status — Ioda Get Status
Advertised read-onlyOpen-world
Inspect recent IODA detection evidence and measurement coverage for one entity over a lookback of 1–24 hours. Collect events, alerts, bgp, ping-slash24 and merit-nt evidence. Partial failures remain explicit and route to standalone tools. recent, stale, no_data and unknown describe observation availability; buckets within the 1800-second publication allowance count as pending, not missing. No alerts is not an all-clear. IODA measures macroscopic connectivity, not one office or a shutdown cause.
ioda_get_status input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"entityType",
"entityCode"
],
"properties": {
"entityCode": {
"type": "string",
"pattern": "^(?:\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Two-letter country code, IODA numeric region code, decimal ASN (AS prefix accepted), or geoasn code joining an ASN and a region or country code (40934-576, 59962-IR); resolve names with ioda_search_entities and pass a returned code here."
},
"entityType": {
"type": "string",
"pattern": "^(?:\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "country, region, asn, or geoasn (one ASN within a region or country); whitespace and case are normalized."
},
"lookbackHours": {
"type": "integer",
"default": 6,
"minimum": 1,
"multipleOf": 1,
"description": "Hours before the captured invocation time; values above 24 are served as 24 with a notice naming the uncovered earlier window. The exact window is returned."
}
},
"additionalProperties": false
}ioda_get_status output schema
{
"type": "object",
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
},
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"entity",
"asOf",
"window",
"detection",
"signals",
"components",
"limitations",
"applied"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"asOf": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Captured invocation time, Unix seconds UTC"
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_entity",
"upstream_bad_request",
"upstream_unprocessable",
"entity_not_found",
"upstream_rate_limited",
"upstream_queue_full",
"upstream_schema"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_entity`: entityCode is incompatible with entityType, zero or out of range. `upstream_bad_request`: IODA rejects the request with an error envelope or an HTTP 400 other than a missing entity. `upstream_unprocessable`: IODA rejects the request with HTTP 422. `entity_not_found`: A numeric source finds no IODA metadata entity for the code and no event, alert, or series was returned. IODA synthesizes metadata for any ASN, so an unknown ASN reads as no data instead. `upstream_rate_limited`: IODA returns HTTP 429. `upstream_queue_full`: The shared request queue is full. `upstream_schema`: IODA data or bucket metadata does not validate, or the response body is over 4 MiB. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"alerts": {
"type": "object",
"required": [
"items",
"pagination"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity",
"datasource",
"time"
],
"properties": {
"time": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Transition Unix seconds UTC"
},
"level": {
"type": [
"string",
"null"
],
"description": "Literal source level"
},
"value": {
"type": [
"number",
"null"
],
"description": "Source measurement at the transition. bgp (Visible /24s), ping-slash24 (Up /24s), and merit-nt (Unique Source IPs) report it in the source unit; gtr (method sarima) reports IODA Traffic divided by 1,000,000 and truncated to an integer."
},
"entity": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Source entity code"
},
"name": {
"type": "string",
"description": "Source entity name"
},
"type": {
"type": [
"string",
"null"
],
"description": "Source entity type, if reported"
},
"attrs": {
"type": "object",
"description": "Source attributes, preserved verbatim",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"subnames": {
"$ref": "#/$defs/__schema0",
"description": "Additional source names, preserved verbatim: usually a list; geoasn search rows carry named parts such as asn and region or country"
}
},
"description": "Entity measured",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"method": {
"type": [
"string",
"null"
],
"description": "Source detection method"
},
"condition": {
"type": [
"string",
"null"
],
"description": "Literal detection condition"
},
"datasource": {
"type": "string",
"description": "Measurement source"
},
"historyValue": {
"type": [
"number",
"null"
],
"description": "Source baseline that value is compared with, on the same per-source scale as value: the source unit for bgp, ping-slash24, and merit-nt; Traffic divided by 1,000,000 and truncated for gtr."
}
},
"description": "Source detection or recovery transition",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "Returned alerts"
},
"pagination": {
"type": "object",
"required": [
"page",
"limit",
"returned",
"more"
],
"properties": {
"more": {
"enum": [
"possible",
"no"
],
"type": "string",
"description": "Whether another row page may exist; no does not verify related-scope membership coverage"
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page size",
"exclusiveMinimum": 0
},
"nextPage": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Next page when another may exist and IODA can continue the request; absent from a full page it cannot continue, whose notice names the route to the rest"
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned record count"
}
},
"description": "Alert page",
"additionalProperties": false
}
},
"description": "Successful alert component",
"additionalProperties": false
},
"entity": {
"type": "object",
"required": [
"entityType",
"entityCode"
],
"properties": {
"entityCode": {
"type": "string",
"description": "Canonical entity code"
},
"entityType": {
"enum": [
"country",
"region",
"asn",
"geoasn"
],
"type": "string",
"description": "Canonical entity type"
}
},
"description": "Requested entity",
"additionalProperties": false
},
"events": {
"type": "object",
"required": [
"items",
"pagination"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity",
"from",
"until",
"score"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Source start Unix seconds UTC; starts at the inclusive requested until can be returned, and overlapping events may start before from"
},
"score": {
"type": "number",
"description": "Unmodified source score"
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Source end Unix seconds UTC; may be clipped to the query boundary and does not establish recovery"
},
"alerts": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity",
"datasource",
"time"
],
"properties": {
"time": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Transition Unix seconds UTC"
},
"level": {
"type": [
"string",
"null"
],
"description": "Literal source level"
},
"value": {
"type": [
"number",
"null"
],
"description": "Source measurement at the transition. bgp (Visible /24s), ping-slash24 (Up /24s), and merit-nt (Unique Source IPs) report it in the source unit; gtr (method sarima) reports IODA Traffic divided by 1,000,000 and truncated to an integer."
},
"entity": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Source entity code"
},
"name": {
"type": "string",
"description": "Source entity name"
},
"type": {
"type": [
"string",
"null"
],
"description": "Source entity type, if reported"
},
"attrs": {
"type": "object",
"description": "Source attributes, preserved verbatim",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"subnames": {
"$ref": "#/$defs/__schema0",
"description": "Additional source names, preserved verbatim: usually a list; geoasn search rows carry named parts such as asn and region or country"
}
},
"description": "Entity measured",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"method": {
"type": [
"string",
"null"
],
"description": "Source detection method"
},
"condition": {
"type": [
"string",
"null"
],
"description": "Literal detection condition"
},
"datasource": {
"type": "string",
"description": "Measurement source"
},
"historyValue": {
"type": [
"number",
"null"
],
"description": "Source baseline that value is compared with, on the same per-source scale as value: the source unit for bgp, ping-slash24, and merit-nt; Traffic divided by 1,000,000 and truncated for gtr."
}
},
"description": "Source detection or recovery transition",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "Nested transitions, when requested"
},
"entity": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Source entity code"
},
"name": {
"type": "string",
"description": "Source entity name"
},
"type": {
"type": [
"string",
"null"
],
"description": "Source entity type, if reported"
},
"attrs": {
"type": "object",
"description": "Source attributes, preserved verbatim",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"subnames": {
"$ref": "#/$defs/__schema0",
"description": "Additional source names, preserved verbatim: usually a list; geoasn search rows carry named parts such as asn and region or country"
}
},
"description": "Entity measured",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"method": {
"type": "string",
"description": "Source detection method"
},
"datasource": {
"type": "string",
"description": "Measurement source"
}
},
"description": "Source outage event with original timing and score",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "Returned events"
},
"pagination": {
"type": "object",
"required": [
"page",
"limit",
"returned",
"more"
],
"properties": {
"more": {
"enum": [
"possible",
"no"
],
"type": "string",
"description": "Whether another row page may exist; no does not verify related-scope membership coverage"
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page size",
"exclusiveMinimum": 0
},
"nextPage": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Next page when another may exist and IODA can continue the request; absent from a full page it cannot continue, whose notice names the route to the rest"
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned record count"
}
},
"description": "Event page",
"additionalProperties": false
}
},
"description": "Successful event component",
"additionalProperties": false
},
"notice": {
"type": "string",
"description": "Result interpretation and concrete next call."
},
"window": {
"type": "object",
"required": [
"from",
"until"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Requested start Unix seconds UTC; component selection and bucket alignment differ"
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Requested end Unix seconds UTC; detections include the boundary while returned signal bucket bounds are exclusive"
}
},
"description": "Exact investigation window",
"additionalProperties": false
},
"applied": {
"type": "object",
"description": "Every normalized input, effective window, filter and pagination value.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
},
"signals": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"unit",
"coverage",
"series"
],
"properties": {
"unit": {
"enum": [
"Visible /24s",
"Up /24s",
"Unique Source IPs"
],
"type": "string",
"description": "IODA's published unit for this source's values. Coarse buckets aggregate underlying samples in the same unit; values need not equal an unweighted mean of finer returned buckets, and non-null aggregates do not prove complete finer-resolution coverage."
},
"series": {
"type": "array",
"items": {
"type": "object",
"required": [
"entityType",
"entityCode",
"datasource",
"from",
"until",
"step",
"nativeStep",
"coverage",
"nonNullCount",
"nullCount",
"pendingCount"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "First aggregate bucket anchor, Unix seconds UTC; alignment can place it before the requested from"
},
"step": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Returned bucket width in seconds",
"exclusiveMinimum": 0
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Exclusive returned bucket bound, Unix seconds UTC; alignment can place it after the requested until"
},
"latest": {
"type": "object",
"required": [
"value",
"bucketFrom",
"bucketUntil"
],
"properties": {
"value": {
"type": "number",
"description": "Latest eligible non-null aggregate"
},
"bucketFrom": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Aggregate start Unix seconds UTC"
},
"bucketUntil": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Aggregate end Unix seconds UTC"
}
},
"description": "Latest completed in-window observation",
"additionalProperties": false
},
"maximum": {
"type": "number",
"description": "Maximum eligible aggregate"
},
"minimum": {
"type": "number",
"description": "Minimum eligible aggregate"
},
"subtype": {
"type": "string",
"description": "Source measurement subtype"
},
"coverage": {
"enum": [
"recent",
"stale",
"no_data",
"unknown"
],
"type": "string",
"description": "Observation availability, never health: recent when the latest completed observation ended within the 1800-second publication allowance of asOf, stale beyond it; no_data for an empty series or one with no observation and a missing bucket; unknown for coarse aggregates, no completed bucket, or only pending buckets"
},
"nullCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Completed in-window missing buckets: interior gaps and trailing nulls that ended more than 1800 seconds before asOf"
},
"datasource": {
"type": "string",
"description": "Measurement source"
},
"entityCode": {
"type": "string",
"description": "Source entity code"
},
"entityFqid": {
"type": "string",
"description": "Source fully qualified entity identifier"
},
"entityName": {
"type": "string",
"description": "Source entity name"
},
"entityType": {
"type": "string",
"description": "Source entity type"
},
"nativeStep": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Native measurement width in seconds",
"exclusiveMinimum": 0
},
"nonNullCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Completed in-window numeric buckets"
},
"pendingCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Completed in-window null buckets after the latest observation that ended within 1800 seconds of asOf; not yet due, not a promise they will be published"
}
},
"description": "Completed in-window bucket statistics for one source subtype",
"additionalProperties": false
},
"description": "Independent subtype summaries"
},
"source": {
"enum": [
"bgp",
"ping-slash24",
"merit-nt"
],
"type": "string",
"description": "Numeric source"
},
"coverage": {
"enum": [
"recent",
"stale",
"no_data",
"unknown"
],
"type": "string",
"description": "Source coverage precedence"
}
},
"description": "Unit, coverage and independent subtype summaries for one core source",
"additionalProperties": false
},
"description": "Coverage for each core source"
},
"detection": {
"enum": [
"observed",
"none_returned",
"unknown"
],
"type": "string",
"description": "Returned lookback detection evidence"
},
"truncated": {
"type": "object",
"required": [
"shown",
"cap"
],
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page capacity",
"exclusiveMinimum": 0
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned records"
}
},
"description": "A full page may have further records; not an exact total.",
"additionalProperties": false
},
"components": {
"type": "array",
"items": {
"type": "object",
"required": [
"component",
"state"
],
"properties": {
"state": {
"enum": [
"ok",
"failed"
],
"type": "string",
"description": "Collection outcome"
},
"failure": {
"type": "object",
"required": [
"code",
"reason",
"message",
"recovery"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Framework error code"
},
"reason": {
"type": "string",
"description": "Classified failure reason"
},
"message": {
"type": "string",
"description": "Sanitized failure message"
},
"recovery": {
"type": "string",
"description": "Concrete standalone-tool recovery"
}
},
"description": "Failed component details",
"additionalProperties": false
},
"component": {
"enum": [
"events",
"alerts",
"bgp",
"ping-slash24",
"merit-nt"
],
"type": "string",
"description": "Evidence component"
},
"provenance": {
"type": "object",
"required": [
"endpoint",
"fetchedAt"
],
"properties": {
"endpoint": {
"type": "string",
"pattern": "^https:\\/\\/api\\.ioda\\.inetintel\\.cc\\.gatech\\.edu\\/v2\\/(?:entities\\/query|outages\\/(?:events|alerts|summary)|signals\\/raw\\/(?:country|region|asn|geoasn)\\/[^\\s/?#]+)$",
"description": "Fixed HTTPS IODA upstream endpoint URL"
},
"copyright": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source attribution"
},
"fetchedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "Fetch completion time UTC"
},
"requestTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source request time"
},
"responseTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source response time"
}
},
"description": "Successful component provenance",
"additionalProperties": false
}
},
"description": "Collection outcome for one status component",
"additionalProperties": false
},
"description": "Five component outcomes in request order"
},
"limitations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Scope, completeness, alignment and freshness qualifications"
}
},
"additionalProperties": false
}ioda_get_status annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ioda_find_outages — Ioda Find Outages
Advertised read-onlyOpen-world
Find IODA outage events overlapping an explicit Unix-second window of at most 31 days. Omit entity filters for global scope, which searches one day outside the window by default instead of 14; global searches over multi-day windows can time out, so narrow the window or add entityType. A code requires its entityType. relatedToType and relatedToCode limit results to entityType entities within one country, region, ASN, or geoasn. Source scores are not an absolute severity scale. Starts at until are included; adjacent windows can duplicate boundary detections. Starts may precede from; ends can be clipped at until and do not establish recovery. ignoreMethods excludes source.method, source.*, or *.method upstream before scoring. includeAlerts adds nested transitions and can increase size. Pages are zero-based; keep filters and limit fixed.
ioda_find_outages input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"from",
"until"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Inclusive Unix seconds UTC; no milliseconds; window at most 31 days. IODA's API holds no outage detections before 2022-01-26 UTC.",
"exclusiveMinimum": 0
},
"page": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page; restart at 0 when changing limit."
},
"limit": {
"type": "integer",
"default": 20,
"minimum": 1,
"multipleOf": 1,
"description": "Default 20; a larger value returns at most 1000 and says so. Keep fixed when continuing."
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Inclusive Unix seconds UTC for transition/event-start selection, after from and no later than now; adjacent windows can duplicate boundary detections.",
"exclusiveMinimum": 0
},
"source": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[bB][gG][pP]|[pP][iI][nN][gG]-[sS][lL][aA][sS][hH]24|[mM][eE][rR][iI][tT]-[nN][tT]|[gG][tT][rR])\\s*)$(?![\\s\\S])",
"description": "bgp, ping-slash24, merit-nt, or gtr; blank means all sources. Case and whitespace are normalized."
},
"entityCode": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Two-letter country code, IODA numeric region code, decimal ASN (AS prefix accepted), or geoasn code joining an ASN and a region or country code (40934-576, 59962-IR); resolve names with ioda_search_entities and pass a returned code here."
},
"entityType": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "country, region, asn, or geoasn (one ASN within a region or country); whitespace and case are normalized."
},
"ignoreMethods": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(?:\\s*(?:(?:(?:[bB][gG][pP]|[pP][iI][nN][gG]-[sS][lL][aA][sS][hH]24|[mM][eE][rR][iI][tT]-[nN][tT]|[gG][tT][rR])\\.(?:\\*|[^\\s.,|*]+)|\\*\\.[^\\s.,|*]+))\\s*)$(?![\\s\\S])",
"description": "One detection method exclusion; case and surrounding whitespace are normalized."
},
"description": "Detection methods to exclude upstream before event construction and scoring; duplicates are removed, and an empty array excludes nothing. Keep fixed across ranking and drill-down calls."
},
"includeAlerts": {
"type": "boolean",
"default": false,
"description": "Include original nested alert transitions and baselines; may substantially increase response size."
},
"relatedToCode": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Scope entity code, normalized like entityCode for relatedToType (IR, 1829, AS42337, 60627-IR); resolve names with ioda_search_entities. Provide with relatedToType."
},
"relatedToType": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "Scope type: country, region, asn, or geoasn. With relatedToCode, returns entityType entities related to that entity, such as the regions or networks of one country. Requires entityType and excludes entityCode; blank is omitted. Outage membership coverage is unverified independently of row pagination; page ioda_search_entities and query selected codes individually."
},
"extendWindowSeconds": {
"type": "integer",
"minimum": 0,
"multipleOf": 1,
"description": "Seconds before from to search for the start of an event overlapping the window, and after until for its recovery; only overlapping events are returned. Defaults to 1209600 (14 days) with entityType and 86400 (one day) without it, because large global extensions can time out; the applied value is echoed. Values above 1209600 are served as 1209600 with a notice. Zero may miss long-running detections."
}
},
"additionalProperties": false
}ioda_find_outages output schema
{
"type": "object",
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
},
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"events",
"pagination",
"provenance",
"applied"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_ignore_methods",
"invalid_entity",
"invalid_scope",
"invalid_window",
"upstream_bad_request",
"upstream_unprocessable",
"entity_not_found",
"upstream_rate_limited",
"upstream_queue_full",
"upstream_timeout",
"upstream_schema"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_ignore_methods`: An explicit source is also excluded by its own source.* entry. `invalid_entity`: entityCode is incompatible with entityType, zero or out of range, or supplied without entityType. `invalid_scope`: relatedToType and relatedToCode are incomplete or incompatible, the code is zero or out of range, or a scope lacks entityType or comes with entityCode. `invalid_window`: Reversed, future, millisecond, or over-31-day window. `upstream_bad_request`: IODA rejects the request with HTTP 400 or an error envelope. `upstream_unprocessable`: IODA rejects the request with HTTP 422. `entity_not_found`: IODA returns an explicit entity 404. `upstream_rate_limited`: IODA returns HTTP 429. `upstream_queue_full`: The shared request queue is full. `upstream_timeout`: IODA does not answer within the per-attempt timeout or the invocation deadline; global searches slow sharply as extendWindowSeconds and the window grow. `upstream_schema`: IODA data or bucket metadata does not validate, or the response body is over 4 MiB. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"events": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity",
"from",
"until",
"score"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Source start Unix seconds UTC; starts at the inclusive requested until can be returned, and overlapping events may start before from"
},
"score": {
"type": "number",
"description": "Unmodified source score"
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Source end Unix seconds UTC; may be clipped to the query boundary and does not establish recovery"
},
"alerts": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity",
"datasource",
"time"
],
"properties": {
"time": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Transition Unix seconds UTC"
},
"level": {
"type": [
"string",
"null"
],
"description": "Literal source level"
},
"value": {
"type": [
"number",
"null"
],
"description": "Source measurement at the transition. bgp (Visible /24s), ping-slash24 (Up /24s), and merit-nt (Unique Source IPs) report it in the source unit; gtr (method sarima) reports IODA Traffic divided by 1,000,000 and truncated to an integer."
},
"entity": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Source entity code"
},
"name": {
"type": "string",
"description": "Source entity name"
},
"type": {
"type": [
"string",
"null"
],
"description": "Source entity type, if reported"
},
"attrs": {
"type": "object",
"description": "Source attributes, preserved verbatim",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"subnames": {
"$ref": "#/$defs/__schema0",
"description": "Additional source names, preserved verbatim: usually a list; geoasn search rows carry named parts such as asn and region or country"
}
},
"description": "Entity measured",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"method": {
"type": [
"string",
"null"
],
"description": "Source detection method"
},
"condition": {
"type": [
"string",
"null"
],
"description": "Literal detection condition"
},
"datasource": {
"type": "string",
"description": "Measurement source"
},
"historyValue": {
"type": [
"number",
"null"
],
"description": "Source baseline that value is compared with, on the same per-source scale as value: the source unit for bgp, ping-slash24, and merit-nt; Traffic divided by 1,000,000 and truncated for gtr."
}
},
"description": "Source detection or recovery transition",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "Nested transitions, when requested"
},
"entity": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Source entity code"
},
"name": {
"type": "string",
"description": "Source entity name"
},
"type": {
"type": [
"string",
"null"
],
"description": "Source entity type, if reported"
},
"attrs": {
"type": "object",
"description": "Source attributes, preserved verbatim",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"subnames": {
"$ref": "#/$defs/__schema0",
"description": "Additional source names, preserved verbatim: usually a list; geoasn search rows carry named parts such as asn and region or country"
}
},
"description": "Entity measured",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"method": {
"type": "string",
"description": "Source detection method"
},
"datasource": {
"type": "string",
"description": "Measurement source"
}
},
"description": "Source outage event with original timing and score",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "Original outage events and source scores without merging or ranking."
},
"notice": {
"type": "string",
"description": "Result interpretation and concrete next call."
},
"applied": {
"type": "object",
"description": "Every normalized input, effective window, filter and pagination value.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
},
"truncated": {
"type": "object",
"required": [
"shown",
"cap"
],
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page capacity",
"exclusiveMinimum": 0
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned records"
}
},
"description": "A full page may have further records; not an exact total.",
"additionalProperties": false
},
"pagination": {
"type": "object",
"required": [
"page",
"limit",
"returned",
"more"
],
"properties": {
"more": {
"enum": [
"possible",
"no"
],
"type": "string",
"description": "Whether another row page may exist; no does not verify related-scope membership coverage"
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page size",
"exclusiveMinimum": 0
},
"nextPage": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Next page when another may exist and IODA can continue the request; absent from a full page it cannot continue, whose notice names the route to the rest"
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned record count"
}
},
"description": "Upstream page and possible continuation.",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"endpoint",
"fetchedAt"
],
"properties": {
"endpoint": {
"type": "string",
"pattern": "^https:\\/\\/api\\.ioda\\.inetintel\\.cc\\.gatech\\.edu\\/v2\\/(?:entities\\/query|outages\\/(?:events|alerts|summary)|signals\\/raw\\/(?:country|region|asn|geoasn)\\/[^\\s/?#]+)$",
"description": "Fixed HTTPS IODA upstream endpoint URL"
},
"copyright": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source attribution"
},
"fetchedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "Fetch completion time UTC"
},
"requestTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source request time"
},
"responseTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source response time"
}
},
"description": "Endpoint and original source attribution.",
"additionalProperties": false
}
},
"additionalProperties": false
}ioda_find_outages annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ioda_summarize_outages — Ioda Summarize Outages
Advertised read-onlyOpen-world
Rank the entities of one entityType by IODA's outage summary score over an explicit Unix-second window of at most 31 days, such as the countries or a country's regions hit hardest this week. Rows keep IODA's order, descending scores.overall. Region rankings can include IODA geolocation catch-alls named [Invalid Region (N)] or Unknown Region in <country>, which are not provinces or states; a notice names them. IODA merges overlapping events from different sources, scores each merged event as the product of its sources' scores, and sums the merged events into overall; each <source>.<method> key sums that source's event scores. Scores are window totals for ranking the rows of one request, not current status, and are not comparable across requests with different windows. Add entityCode for one entity, or relatedToType and relatedToCode to rank entityType entities within one country, region, ASN, or geoasn; large type-only rankings can time out. Event-start selection includes until, so adjacent windows can duplicate boundary detections. ignoreMethods excludes source.method, source.*, or *.method upstream before scoring; keep exclusions fixed when comparing rankings or drilling into events and alerts. An empty result is not an all-clear. Pages are zero-based; keep filters and limit fixed.
ioda_summarize_outages input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"entityType",
"from",
"until"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Inclusive Unix seconds UTC; no milliseconds; window at most 31 days. IODA's API holds no outage detections before 2022-01-26 UTC.",
"exclusiveMinimum": 0
},
"page": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page; restart at 0 when changing limit."
},
"limit": {
"type": "integer",
"default": 20,
"minimum": 1,
"multipleOf": 1,
"description": "Default 20; a larger value returns at most 1000 and says so. Keep fixed when continuing."
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Inclusive Unix seconds UTC for transition/event-start selection, after from and no later than now; adjacent windows can duplicate boundary detections.",
"exclusiveMinimum": 0
},
"entityCode": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Two-letter country code, IODA numeric region code, decimal ASN (AS prefix accepted), or geoasn code joining an ASN and a region or country code (40934-576, 59962-IR); resolve names with ioda_search_entities and pass a returned code here."
},
"entityType": {
"type": "string",
"pattern": "^(?:\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "country, region, asn, or geoasn (one ASN within a region or country); whitespace and case are normalized."
},
"ignoreMethods": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(?:\\s*(?:(?:(?:[bB][gG][pP]|[pP][iI][nN][gG]-[sS][lL][aA][sS][hH]24|[mM][eE][rR][iI][tT]-[nN][tT]|[gG][tT][rR])\\.(?:\\*|[^\\s.,|*]+)|\\*\\.[^\\s.,|*]+))\\s*)$(?![\\s\\S])",
"description": "One detection method exclusion; case and surrounding whitespace are normalized."
},
"description": "Detection methods to exclude upstream before event construction and scoring; duplicates are removed, and an empty array excludes nothing. Keep fixed across ranking and drill-down calls."
},
"relatedToCode": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Scope entity code, normalized like entityCode for relatedToType (IR, 1829, AS42337, 60627-IR); resolve names with ioda_search_entities. Provide with relatedToType."
},
"relatedToType": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "Scope type: country, region, asn, or geoasn. With relatedToCode, returns entityType entities related to that entity, such as the regions or networks of one country. Requires entityType and excludes entityCode; blank is omitted. Outage membership coverage is unverified independently of row pagination; page ioda_search_entities and query selected codes individually."
},
"extendWindowSeconds": {
"type": "integer",
"default": 1209600,
"minimum": 0,
"multipleOf": 1,
"description": "Seconds before from to search for the start of an event overlapping the window, and after until for its recovery; defaults to 1209600 (14 days), IODA's default. Values above 1209600 are served as 1209600 with a notice. Large extensions on type-only rankings can time out; zero may miss long-running detections."
}
},
"additionalProperties": false
}ioda_summarize_outages output schema
{
"type": "object",
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
},
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"summaries",
"pagination",
"provenance",
"applied"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_entity",
"invalid_scope",
"invalid_window",
"upstream_bad_request",
"upstream_unprocessable",
"entity_not_found",
"upstream_rate_limited",
"upstream_queue_full",
"upstream_timeout",
"upstream_schema"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_entity`: entityCode is incompatible with entityType, zero or out of range. `invalid_scope`: relatedToType and relatedToCode are incomplete or incompatible, the code is zero or out of range, or a scope comes with entityCode. `invalid_window`: Reversed, future, millisecond, or over-31-day window. `upstream_bad_request`: IODA rejects the request with HTTP 400 or an error envelope. `upstream_unprocessable`: IODA rejects the request with HTTP 422. `entity_not_found`: IODA returns an explicit entity 404. `upstream_rate_limited`: IODA returns HTTP 429. `upstream_queue_full`: The shared request queue is full. `upstream_timeout`: IODA does not answer within the per-attempt timeout or the invocation deadline; type-only rankings such as every region are the slowest, and slow further as extendWindowSeconds and the window grow. `upstream_schema`: IODA summary rows lack an entity, a numeric scores.overall, or an integer event_cnt, carry a non-numeric score, or arrive in a response body over 4 MiB. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Result interpretation and concrete next call."
},
"applied": {
"type": "object",
"description": "Every normalized input, effective window, filter and pagination value.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
},
"summaries": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity",
"scores",
"event_cnt"
],
"properties": {
"entity": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Source entity code"
},
"name": {
"type": "string",
"description": "Source entity name"
},
"type": {
"type": [
"string",
"null"
],
"description": "Source entity type, if reported"
},
"attrs": {
"type": "object",
"description": "Source attributes, preserved verbatim",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"subnames": {
"$ref": "#/$defs/__schema0",
"description": "Additional source names, preserved verbatim: usually a list; geoasn search rows carry named parts such as asn and region or country"
}
},
"description": "Entity ranked",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"scores": {
"type": "object",
"required": [
"overall"
],
"properties": {
"overall": {
"type": "number",
"description": "IODA's ranking score: overlapping events from different sources are merged, each merged event scores the product of its sources' scores, and overall sums the merged events"
}
},
"description": "Unmodified window-total scores: overall plus one sum of event scores per <source>.<method> key, such as bgp.median or gtr.sarima",
"additionalProperties": {
"type": "number"
}
},
"event_cnt": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "IODA's count of the entity's source events before merging"
}
},
"description": "One entity's unmodified IODA outage summary for the window",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "IODA's per-entity summaries in its own order, descending scores.overall."
},
"truncated": {
"type": "object",
"required": [
"shown",
"cap"
],
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page capacity",
"exclusiveMinimum": 0
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned records"
}
},
"description": "A full page may have further records; not an exact total.",
"additionalProperties": false
},
"pagination": {
"type": "object",
"required": [
"page",
"limit",
"returned",
"more"
],
"properties": {
"more": {
"enum": [
"possible",
"no"
],
"type": "string",
"description": "Whether another row page may exist; no does not verify related-scope membership coverage"
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page size",
"exclusiveMinimum": 0
},
"nextPage": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Next page when another may exist and IODA can continue the request; absent from a full page it cannot continue, whose notice names the route to the rest"
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned record count"
}
},
"description": "Upstream page and possible continuation.",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"endpoint",
"fetchedAt"
],
"properties": {
"endpoint": {
"type": "string",
"pattern": "^https:\\/\\/api\\.ioda\\.inetintel\\.cc\\.gatech\\.edu\\/v2\\/(?:entities\\/query|outages\\/(?:events|alerts|summary)|signals\\/raw\\/(?:country|region|asn|geoasn)\\/[^\\s/?#]+)$",
"description": "Fixed HTTPS IODA upstream endpoint URL"
},
"copyright": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source attribution"
},
"fetchedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "Fetch completion time UTC"
},
"requestTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source request time"
},
"responseTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source response time"
}
},
"description": "Endpoint and original source attribution.",
"additionalProperties": false
}
},
"additionalProperties": false
}ioda_summarize_outages annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ioda_get_signals — Ioda Get Signals
Advertised read-onlyOpen-world
Fetch numeric BGP visibility, active IPv4 /24 probing, Merit telescope, or Google Transparency Report traffic series for one entity in an explicit Unix-second window of at most 31 days. source is required: bgp, ping-slash24, merit-nt, or gtr (countries only). Nulls are not zero connectivity: trailing nulls in buckets not yet ended or ended within the publication allowance before the call (1800 seconds for bgp and ping-slash24, 10800 for merit-nt and gtr) are usually unpublished, and every other null is a missing observation; the notice counts each trailing class. maxPoints requests upstream aggregation, not first-N samples; smaller values lose temporal resolution. Returned series retain aligned boundary buckets with exclusive returned until bounds that may extend beyond requested bounds; timestamps and intervals support cross-source comparisons.
ioda_get_signals input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"entityType",
"entityCode",
"from",
"until",
"source"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested start Unix seconds UTC; window at most 31 days. Aligned returned buckets may begin earlier. IODA's API holds no merit-nt observations before 2022-01-09 UTC, no bgp before 2022-01-18, and no ping-slash24 before 2022-02-02.",
"exclusiveMinimum": 0
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested end Unix seconds UTC, after from and no later than now. Returned bucket bounds are exclusive and may extend beyond this requested bound due to alignment.",
"exclusiveMinimum": 0
},
"source": {
"type": "string",
"pattern": "^(?:\\s*(?:[bB][gG][pP]|[pP][iI][nN][gG]-[sS][lL][aA][sS][hH]24|[mM][eE][rR][iI][tT]-[nN][tT]|[gG][tT][rR])\\s*)$(?![\\s\\S])",
"description": "Exactly bgp, ping-slash24, merit-nt, or gtr; case and whitespace normalized. gtr (Google Transparency Report traffic) covers countries only; ucsd-nt is not supported."
},
"maxPoints": {
"type": "integer",
"default": 200,
"minimum": 1,
"multipleOf": 1,
"description": "Upstream aggregation target, not a local sample cap; smaller targets lose temporal resolution. Default 200; a value above 10000 is served as 10000 and says so."
},
"entityCode": {
"type": "string",
"pattern": "^(?:\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Two-letter country code, IODA numeric region code, decimal ASN (AS prefix accepted), or geoasn code joining an ASN and a region or country code (40934-576, 59962-IR); resolve names with ioda_search_entities and pass a returned code here."
},
"entityType": {
"type": "string",
"pattern": "^(?:\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "country, region, asn, or geoasn (one ASN within a region or country); whitespace and case are normalized."
}
},
"additionalProperties": false
}ioda_get_signals output schema
{
"type": "object",
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
},
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"series",
"semantics",
"provenance",
"applied"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_entity",
"invalid_window",
"upstream_bad_request",
"upstream_unprocessable",
"entity_not_found",
"upstream_rate_limited",
"upstream_queue_full",
"upstream_schema"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_entity`: entityCode is incompatible with entityType, zero or out of range. `invalid_window`: Reversed, future, millisecond, or over-31-day window. `upstream_bad_request`: IODA rejects the request with an error envelope or an HTTP 400 other than a missing entity. `upstream_unprocessable`: IODA rejects the request with HTTP 422. `entity_not_found`: IODA has no metadata entity for a country, region, or geoasn code (HTTP 400), or returns HTTP 404. IODA synthesizes metadata for any ASN, so an unknown ASN returns no series instead. `upstream_rate_limited`: IODA returns HTTP 429. `upstream_queue_full`: The shared request queue is full. `upstream_schema`: IODA data or bucket metadata does not validate, or the response body is over 4 MiB. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notice": {
"type": "string",
"description": "Result interpretation and concrete next call."
},
"series": {
"type": "array",
"items": {
"type": "object",
"required": [
"entityType",
"entityCode",
"datasource",
"from",
"until",
"step",
"nativeStep",
"values"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "First aggregate bucket anchor, Unix seconds UTC; alignment can place it before the requested from"
},
"step": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Returned bucket width in seconds",
"exclusiveMinimum": 0
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Exclusive returned bucket bound, Unix seconds UTC; alignment can place it after the requested until"
},
"values": {
"type": "array",
"items": {
"type": [
"number",
"null"
]
},
"description": "All numeric or missing upstream aggregate values; a non-null coarse value can conceal missing finer observations"
},
"subtype": {
"type": "string",
"description": "Source measurement subtype"
},
"datasource": {
"type": "string",
"description": "Measurement source"
},
"entityCode": {
"type": "string",
"description": "Source entity code"
},
"entityFqid": {
"type": "string",
"description": "Source fully qualified entity identifier"
},
"entityName": {
"type": "string",
"description": "Source entity name"
},
"entityType": {
"type": "string",
"description": "Source entity type"
},
"nativeStep": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Native measurement width in seconds",
"exclusiveMinimum": 0
}
},
"description": "Numeric source buckets, including missing observations",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "All numeric subtypes and buckets, preserving nulls and aligned bounds."
},
"applied": {
"type": "object",
"description": "Every normalized input, effective window, filter and pagination value.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
},
"semantics": {
"type": "object",
"required": [
"source",
"measurement",
"unit",
"caveat"
],
"properties": {
"unit": {
"enum": [
"Visible /24s",
"Up /24s",
"Unique Source IPs",
"Traffic"
],
"type": "string",
"description": "IODA's published unit for this source's values. Coarse buckets aggregate underlying samples in the same unit; values need not equal an unweighted mean of finer returned buckets, and non-null aggregates do not prove complete finer-resolution coverage."
},
"caveat": {
"type": "string",
"description": "Limits on interpretation."
},
"source": {
"enum": [
"bgp",
"ping-slash24",
"merit-nt",
"gtr"
],
"type": "string",
"description": "Requested numeric source."
},
"measurement": {
"type": "string",
"description": "What this source measures."
}
},
"description": "Source-specific measurement semantics and IODA unit.",
"additionalProperties": false
},
"truncated": {
"type": "object",
"required": [
"shown",
"cap"
],
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page capacity",
"exclusiveMinimum": 0
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned records"
}
},
"description": "A full page may have further records; not an exact total.",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"endpoint",
"fetchedAt"
],
"properties": {
"endpoint": {
"type": "string",
"pattern": "^https:\\/\\/api\\.ioda\\.inetintel\\.cc\\.gatech\\.edu\\/v2\\/(?:entities\\/query|outages\\/(?:events|alerts|summary)|signals\\/raw\\/(?:country|region|asn|geoasn)\\/[^\\s/?#]+)$",
"description": "Fixed HTTPS IODA upstream endpoint URL"
},
"copyright": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source attribution"
},
"fetchedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "Fetch completion time UTC"
},
"requestTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source request time"
},
"responseTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source response time"
}
},
"description": "Endpoint and original source attribution.",
"additionalProperties": false
}
},
"additionalProperties": false
}ioda_get_signals annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}ioda_get_alerts — Ioda Get Alerts
Advertised read-onlyOpen-world
Retrieve IODA detection and recovery transitions in an explicit Unix-second window of at most 31 days. Omit entity filters for global scope; a code requires entityType. relatedToType and relatedToCode limit results to entityType entities within one country, region, ASN, or geoasn, served at page 0 only. Each transition retains its source, level, condition, value and baseline; levels and baselines are not a source-independent severity scale. A recovery's historyValue can be a baseline IODA re-based during a long event; compare its value with the detection's historyValue and condition. Transitions include both requested bounds, widened by extendWindowSeconds; adjacent windows can duplicate boundary detections. ignoreMethods excludes source.method, source.*, or *.method upstream. Missing transitions do not establish health. Pages are zero-based; keep filters and limit fixed.
ioda_get_alerts input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"from",
"until"
],
"properties": {
"from": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Inclusive Unix seconds UTC; no milliseconds; window at most 31 days. IODA's API holds no outage detections before 2022-01-26 UTC.",
"exclusiveMinimum": 0
},
"page": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page; restart at 0 when changing limit."
},
"limit": {
"type": "integer",
"default": 20,
"minimum": 1,
"multipleOf": 1,
"description": "Default 20; a larger value returns at most 1000 and says so. Keep fixed when continuing."
},
"until": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Inclusive Unix seconds UTC for transition/event-start selection, after from and no later than now; adjacent windows can duplicate boundary detections.",
"exclusiveMinimum": 0
},
"source": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[bB][gG][pP]|[pP][iI][nN][gG]-[sS][lL][aA][sS][hH]24|[mM][eE][rR][iI][tT]-[nN][tT]|[gG][tT][rR])\\s*)$(?![\\s\\S])",
"description": "bgp, ping-slash24, merit-nt, or gtr; blank means all sources. Case and whitespace are normalized."
},
"entityCode": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Two-letter country code, IODA numeric region code, decimal ASN (AS prefix accepted), or geoasn code joining an ASN and a region or country code (40934-576, 59962-IR); resolve names with ioda_search_entities and pass a returned code here."
},
"entityType": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "country, region, asn, or geoasn (one ASN within a region or country); whitespace and case are normalized."
},
"ignoreMethods": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(?:\\s*(?:(?:(?:[bB][gG][pP]|[pP][iI][nN][gG]-[sS][lL][aA][sS][hH]24|[mM][eE][rR][iI][tT]-[nN][tT]|[gG][tT][rR])\\.(?:\\*|[^\\s.,|*]+)|\\*\\.[^\\s.,|*]+))\\s*)$(?![\\s\\S])",
"description": "One detection method exclusion; case and surrounding whitespace are normalized."
},
"description": "Detection methods to exclude upstream before event construction and scoring; duplicates are removed, and an empty array excludes nothing. Keep fixed across ranking and drill-down calls."
},
"relatedToCode": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[a-zA-Z]{2}|(?:[aA][sS])?[0-9]+(?:-(?:[0-9]+|[a-zA-Z]{2}))?)\\s*)$(?![\\s\\S])",
"description": "Scope entity code, normalized like entityCode for relatedToType (IR, 1829, AS42337, 60627-IR); resolve names with ioda_search_entities. Provide with relatedToType."
},
"relatedToType": {
"type": "string",
"pattern": "^(?:\\s*|\\s*(?:[cC][oO][uU][nN][tT][rR][yY]|[rR][eE][gG][iI][oO][nN]|[aA][sS][nN]|[gG][eE][oO][aA][sS][nN])\\s*)$(?![\\s\\S])",
"description": "Scope type: country, region, asn, or geoasn. With relatedToCode, returns entityType entities related to that entity, such as the regions or networks of one country. Requires entityType and excludes entityCode; blank is omitted. Outage membership coverage is unverified independently of row pagination; page ioda_search_entities and query selected codes individually."
},
"extendWindowSeconds": {
"type": "integer",
"default": 0,
"minimum": 0,
"multipleOf": 1,
"description": "Seconds before from and after until to also return transitions from; zero, the default, returns only transitions inside the window. Without entityType, large extensions are slow globally and can time out, so add entityType or keep the extension small. Values above 1209600 (14 days) are served as 1209600 with a notice."
}
},
"additionalProperties": false
}ioda_get_alerts output schema
{
"type": "object",
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
}
]
},
"__schema1": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/__schema1"
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
}
]
}
},
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alerts",
"pagination",
"provenance",
"applied"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"invalid_ignore_methods",
"invalid_entity",
"invalid_scope",
"invalid_window",
"upstream_bad_request",
"upstream_unprocessable",
"entity_not_found",
"upstream_rate_limited",
"upstream_queue_full",
"upstream_timeout",
"upstream_schema"
],
"description": "Machine-readable failure mode. Declared by this tool: `invalid_ignore_methods`: An explicit source is also excluded by its own source.* entry. `invalid_entity`: entityCode is incompatible with entityType, zero or out of range, or supplied without entityType. `invalid_scope`: relatedToType and relatedToCode are incomplete or incompatible, the code is zero or out of range, a scope lacks entityType or comes with entityCode, or a scope asks for a page above 0. `invalid_window`: Reversed, future, millisecond, or over-31-day window. `upstream_bad_request`: IODA rejects the request with HTTP 400 or an error envelope. `upstream_unprocessable`: IODA rejects the request with HTTP 422. `entity_not_found`: IODA returns an explicit entity 404. `upstream_rate_limited`: IODA returns HTTP 429. `upstream_queue_full`: The shared request queue is full. `upstream_timeout`: IODA does not answer within the per-attempt timeout or the invocation deadline; global searches slow sharply as extendWindowSeconds and the window grow. `upstream_schema`: IODA data or bucket metadata does not validate, or the response body is over 4 MiB. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"alerts": {
"type": "array",
"items": {
"type": "object",
"required": [
"entity",
"datasource",
"time"
],
"properties": {
"time": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "Transition Unix seconds UTC"
},
"level": {
"type": [
"string",
"null"
],
"description": "Literal source level"
},
"value": {
"type": [
"number",
"null"
],
"description": "Source measurement at the transition. bgp (Visible /24s), ping-slash24 (Up /24s), and merit-nt (Unique Source IPs) report it in the source unit; gtr (method sarima) reports IODA Traffic divided by 1,000,000 and truncated to an integer."
},
"entity": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Source entity code"
},
"name": {
"type": "string",
"description": "Source entity name"
},
"type": {
"type": [
"string",
"null"
],
"description": "Source entity type, if reported"
},
"attrs": {
"type": "object",
"description": "Source attributes, preserved verbatim",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"subnames": {
"$ref": "#/$defs/__schema0",
"description": "Additional source names, preserved verbatim: usually a list; geoasn search rows carry named parts such as asn and region or country"
}
},
"description": "Entity measured",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"method": {
"type": [
"string",
"null"
],
"description": "Source detection method"
},
"condition": {
"type": [
"string",
"null"
],
"description": "Literal detection condition"
},
"datasource": {
"type": "string",
"description": "Measurement source"
},
"historyValue": {
"type": [
"number",
"null"
],
"description": "Source baseline that value is compared with, on the same per-source scale as value: the source unit for bgp, ping-slash24, and merit-nt; Traffic divided by 1,000,000 and truncated for gtr."
}
},
"description": "Source detection or recovery transition",
"additionalProperties": {
"$ref": "#/$defs/__schema0"
}
},
"description": "Literal detection and recovery transitions with source baselines."
},
"notice": {
"type": "string",
"description": "Result interpretation and concrete next call."
},
"applied": {
"type": "object",
"description": "Every normalized input, effective window, filter and pagination value.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"$ref": "#/$defs/__schema1"
}
},
"truncated": {
"type": "object",
"required": [
"shown",
"cap"
],
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page capacity",
"exclusiveMinimum": 0
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned records"
}
},
"description": "A full page may have further records; not an exact total.",
"additionalProperties": false
},
"pagination": {
"type": "object",
"required": [
"page",
"limit",
"returned",
"more"
],
"properties": {
"more": {
"enum": [
"possible",
"no"
],
"type": "string",
"description": "Whether another row page may exist; no does not verify related-scope membership coverage"
},
"page": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Zero-based upstream page"
},
"limit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Requested page size",
"exclusiveMinimum": 0
},
"nextPage": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Next page when another may exist and IODA can continue the request; absent from a full page it cannot continue, whose notice names the route to the rest"
},
"returned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Returned record count"
}
},
"description": "Upstream page and possible continuation.",
"additionalProperties": false
},
"provenance": {
"type": "object",
"required": [
"endpoint",
"fetchedAt"
],
"properties": {
"endpoint": {
"type": "string",
"pattern": "^https:\\/\\/api\\.ioda\\.inetintel\\.cc\\.gatech\\.edu\\/v2\\/(?:entities\\/query|outages\\/(?:events|alerts|summary)|signals\\/raw\\/(?:country|region|asn|geoasn)\\/[^\\s/?#]+)$",
"description": "Fixed HTTPS IODA upstream endpoint URL"
},
"copyright": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source attribution"
},
"fetchedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
"description": "Fetch completion time UTC"
},
"requestTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source request time"
},
"responseTime": {
"$ref": "#/$defs/__schema0",
"description": "Unmodified source response time"
}
},
"description": "Endpoint and original source attribution.",
"additionalProperties": false
}
},
"additionalProperties": false
}ioda_get_alerts annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}Prompts
0 advertised
Resources
1 advertised
ioda-outages-guide
Gates and workflows for the ioda_* tools (IODA Internet outage detection). Covers resolving countries, provinces, and networks to IODA codes, asn vs geoasn, finding the current time, publication lag, signal resolution, and reading alerts, rankings, and BGP, probing, telescope, and Google traffic signals without over-claiming. Use when investigating an Internet shutdown or outage, checking whether a place or network is degraded now, ranking outages, or charting connectivity.
ioda-outages-guide URI
skill://ioda-outages-guide/SKILL.mdio.modelcontextprotocol/skills
io.modelcontextprotocol/skills URI template
skill://{+path}30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 643 ms
- 95th percentile latency
- 643 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 643 ms · metadata changed · 6 tool(s), 1 resource(s), 1 resource template(s), 0 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http ioda-outages-mcp-server-caseyjhand https://ioda-outages.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add ioda-outages-mcp-server-caseyjhand --url https://ioda-outages.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"ioda-outages-mcp-server-caseyjhand": {
"url": "https://ioda-outages.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"ioda-outages-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://ioda-outages.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"ioda-outages-mcp-server-caseyjhand": {
"type": "http",
"url": "https://ioda-outages.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http ioda-outages-mcp-server-caseyjhand https://ioda-outages.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
{
"mcpServers": {
"ioda-outages-mcp-server-caseyjhand": {
"url": "https://ioda-outages.caseyjhand.com/mcp"
}
}
}Windsurf
Windsurf configuration
{
"mcpServers": {
"ioda-outages-mcp-server-caseyjhand": {
"serverUrl": "https://ioda-outages.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like ioda-outages-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.