Skip to content
Cloudflare API
Start here
API Reference
Radar
Annotations

Get latest annotations

radar.annotations.list(AnnotationListParams**kwargs) -> AnnotationListResponse
GET/radar/annotations

Retrieves the latest annotations.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
User Details WriteUser Details Read
ParametersExpand Collapse
asn: Optional[int]

Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.

data_source: Optional[Literal["ALL", "AI_BOTS", "AI_GATEWAY", 22 more]]

Filters results by data source.

One of the following:
"ALL"
"AI_BOTS"
"AI_GATEWAY"
"BGP"
"BOTS"
"CONNECTION_ANOMALY"
"CT"
"DNS"
"DNS_MAGNITUDE"
"DNS_AS112"
"DOS"
"EMAIL_ROUTING"
"EMAIL_SECURITY"
"FW"
"FW_PG"
"HTTP"
"HTTP_CONTROL"
"HTTP_CRAWLER_REFERER"
"HTTP_ORIGINS"
"IQI"
"LEAKED_CREDENTIALS"
"NET"
"ROBOTS_TXT"
"SPEED"
"WORKERS_AI"
date_end: Optional[Union[str, datetime]]

End of the date range (inclusive).

formatdate-time
date_range: Optional[str]

Filters results by date range.

date_start: Optional[Union[str, datetime]]

Start of the date range (inclusive).

formatdate-time
event_type: Optional[Literal["EVENT", "GENERAL", "OUTAGE", 3 more]]

Filters results by event type.

One of the following:
"EVENT"
"GENERAL"
"OUTAGE"
"PARTIAL_PROJECTION"
"PIPELINE"
"TRAFFIC_ANOMALY"
format: Optional[Literal["JSON", "CSV"]]

Format in which results will be returned.

One of the following:
"JSON"
"CSV"
limit: Optional[int]

Limits the number of objects returned in the response.

exclusiveMinimum
minimum0
location: Optional[str]

Filters results by location. Specify an alpha-2 location code.

maxLength2
minLength2
offset: Optional[int]

Skips the specified number of objects before fetching the results.

minimum0
origin: Optional[str]

Filters results by origin.

maxLength100
ReturnsExpand Collapse
class AnnotationListResponse: …
annotations: List[Annotation]
id: str
asns: List[int]
asns_details: List[AnnotationASNsDetail]
asn: str
name: str
locations: Optional[AnnotationASNsDetailLocations]
code: str
name: str
data_source: str
event_type: str
locations: List[str]
locations_details: List[AnnotationLocationsDetail]
code: str
name: str
origins: List[str]
origins_details: List[AnnotationOriginsDetail]
name: str
origin: str
outage: AnnotationOutage
outage_cause: str
outage_type: str
start_date: str
description: Optional[str]
end_date: Optional[str]
linked_url: Optional[str]
scope: Optional[str]

Get latest annotations

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
annotations = client.radar.annotations.list()
print(annotations.annotations)
{
  "result": {
    "annotations": [
      {
        "id": "550",
        "asns": [
          189
        ],
        "asnsDetails": [
          {
            "asn": "189",
            "name": "LUMEN-LEGACY-L3-PARTITION",
            "locations": {
              "code": "US",
              "name": "United States"
            }
          }
        ],
        "dataSource": "ALL",
        "eventType": "OUTAGE",
        "locations": [
          "US"
        ],
        "locationsDetails": [
          {
            "code": "US",
            "name": "United States"
          }
        ],
        "origins": [
          "amazon-us-east-1"
        ],
        "originsDetails": [
          {
            "name": "us-east-1 Amazon Web Services",
            "origin": "amazon-us-east-1"
          }
        ],
        "outage": {
          "outageCause": "CABLE_CUT",
          "outageType": "NATIONWIDE"
        },
        "startDate": "2022-09-06T10:00:28Z",
        "description": "example",
        "endDate": "2022-09-08T10:00:28Z",
        "linkedUrl": "http://example.com",
        "scope": "Colima, Michoacán, México"
      }
    ]
  },
  "success": true
}
Returns Examples
{
  "result": {
    "annotations": [
      {
        "id": "550",
        "asns": [
          189
        ],
        "asnsDetails": [
          {
            "asn": "189",
            "name": "LUMEN-LEGACY-L3-PARTITION",
            "locations": {
              "code": "US",
              "name": "United States"
            }
          }
        ],
        "dataSource": "ALL",
        "eventType": "OUTAGE",
        "locations": [
          "US"
        ],
        "locationsDetails": [
          {
            "code": "US",
            "name": "United States"
          }
        ],
        "origins": [
          "amazon-us-east-1"
        ],
        "originsDetails": [
          {
            "name": "us-east-1 Amazon Web Services",
            "origin": "amazon-us-east-1"
          }
        ],
        "outage": {
          "outageCause": "CABLE_CUT",
          "outageType": "NATIONWIDE"
        },
        "startDate": "2022-09-06T10:00:28Z",
        "description": "example",
        "endDate": "2022-09-08T10:00:28Z",
        "linkedUrl": "http://example.com",
        "scope": "Colima, Michoacán, México"
      }
    ]
  },
  "success": true
}