Skip to content
Cloudflare API
Start here
API Reference
Cloudforce One
Threat Events

Filter and list events

cloudforce_one.threat_events.list(ThreatEventListParams**kwargs) -> ThreatEventListResponse
GET/accounts/{account_id}/cloudforce-one/events

Use datasetId=all or datasetId=* for the legacy all-datasets scope, datasetId=analytics for datasets with isAnalytics=true, or datasetId=operational for datasets with isAnalytics=false (limited to 50). Scope values must be used alone. When datasetId is unspecified, events are listed from the default Cloudforce One Threat Events dataset. To list existing datasets, use the List Datasets endpoint.

Security

API Token

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

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
Accepted Permissions (at least one required)
Cloudforce One WriteCloudforce One Read
ParametersExpand Collapse
account_id: str

Account ID.

cache: Optional[Literal["from-graph"]]

Cache strategy. ‘from-graph’ serves results from the graph-node KV cache when all requested UUIDs are cached; falls back to normal path on partial/zero hit.

cursor: Optional[str]

Cursor for pagination. When provided, filters are embedded in the cursor so you only need to pass cursor and pageSize. Returned in the previous response’s result_info.cursor field. Use cursor-based pagination for deep pagination (beyond 100,000 records) or for optimal performance.

dataset_id: Optional[Sequence[str]]

Dataset UUIDs to query, or one standalone scope value: ‘all’/’*’ for the legacy all-datasets behavior, ‘analytics’ for isAnalytics=true datasets, or ‘operational’ for isAnalytics=false datasets. If not provided, uses the default dataset.

force_refresh: Optional[bool]
format: Optional[Literal["json", "stix2", "taxii"]]
One of the following:
"json"
"stix2"
"taxii"
order: Optional[Literal["asc", "desc"]]
One of the following:
"asc"
"desc"
order_by: Optional[str]
page: Optional[float]

Page number (1-indexed) for offset-based pagination. Limited to offset of 100,000 records. For deep pagination, use cursor-based pagination instead.

page_size: Optional[float]

Number of results per page. Maximum 25,000.

One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
One of the following:
search_branches: Optional[Iterable[Iterable[SearchBranch]]]

JSON-encoded. OR branches of structured search filters. Filters within a branch are AND’d, branches are OR’d, and the result is AND’d with search: AND(search) AND OR(AND(branch 1), ...). Max 8 branches of 1-10 conditions each. Not supported for analytics datasets, and indicator filters are not yet supported inside branches. Cursor pages carry the original branches, so do not resend them with cursor.

One of the following:
class SearchBranchUnionMember0: …
field: Literal["attacker", "attackerCountry", "category", 12 more]
One of the following:
"attacker"
"attackerCountry"
"category"
"createdAt"
"date"
"event"
"indicator"
"indicatorType"
"mitreAttack"
"mitreCapec"
"tags"
"targetCountry"
"targetIndustry"
"tlp"
"uuid"
op: Literal["equals", "not", "gt", 8 more]
One of the following:
"equals"
"not"
"gt"
"gte"
"lt"
"lte"
"like"
"contains"
"startsWith"
"endsWith"
"find"
value: str
maxLength512
minLength1
class SearchBranchUnionMember1: …
field: Literal["attacker", "attackerCountry", "category", 12 more]
One of the following:
"attacker"
"attackerCountry"
"category"
"createdAt"
"date"
"event"
"indicator"
"indicatorType"
"mitreAttack"
"mitreCapec"
"tags"
"targetCountry"
"targetIndustry"
"tlp"
"uuid"
op: Literal["in"]
value: Sequence[str]
class SearchBranchUnionMember2: …
field: Literal["killChain"]
op: Literal["equals", "not", "gt", 3 more]
One of the following:
"equals"
"not"
"gt"
"gte"
"lt"
"lte"
value: Union[float, str]
One of the following:
float
str
class SearchBranchUnionMember3: …
field: Literal["killChain"]
op: Literal["in"]
value: Sequence[Union[float, str]]
One of the following:
float
str
class SearchBranchUnionMember4: …
field: Literal["hasChildren"]
op: Literal["equals", "not", "gt", 3 more]
One of the following:
"equals"
"not"
"gt"
"gte"
"lt"
"lte"
value: Union[bool, object]
One of the following:
bool
object
class SearchBranchUnionMember5: …
field: Literal["hasChildren"]
op: Literal["in"]
value: Iterable[Union[bool, object]]
One of the following:
bool
object
ReturnsExpand Collapse
List[ThreatEventListResponseItem]
attacker: str
attacker_country: str
attacker_country_alpha3: str
category: str
dataset_id: str
date: str
event: str
has_children: bool
indicator: str
indicator_type: str
indicator_type_id: float
kill_chain: float
mitre_attack: List[str]
mitre_capec: List[str]
num_referenced: float
num_references: float
raw_id: str
referenced: List[str]
referenced_ids: List[float]
references: List[str]
references_ids: List[float]
tags: List[str]
target_country: str
target_country_alpha3: str
target_industry: str
tlp: str
uuid: str
insight: Optional[str]
releasability_id: Optional[str]

Filter and list events

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
threat_events = client.cloudforce_one.threat_events.list(
    account_id="account_id",
)
print(threat_events)
[
  {
    "attacker": "Flying Yeti",
    "attackerCountry": "CN",
    "attackerCountryAlpha3": "CHN",
    "category": "Domain Resolution",
    "datasetId": "dataset-example-id",
    "date": "2022-04-01T00:00:00Z",
    "event": "An attacker registered the domain domain.com",
    "hasChildren": true,
    "indicator": "domain.com",
    "indicatorType": "domain",
    "indicatorTypeId": 5,
    "killChain": 0,
    "mitreAttack": [
      " "
    ],
    "mitreCapec": [
      " "
    ],
    "numReferenced": 0,
    "numReferences": 0,
    "rawId": "453gw34w3",
    "referenced": [
      " "
    ],
    "referencedIds": [
      0
    ],
    "references": [
      " "
    ],
    "referencesIds": [
      0
    ],
    "tags": [
      "malware"
    ],
    "targetCountry": "US",
    "targetCountryAlpha3": "USA",
    "targetIndustry": "Agriculture",
    "tlp": "amber",
    "uuid": "12345678-1234-1234-1234-1234567890ab",
    "insight": "insight",
    "releasabilityId": "releasabilityId"
  }
]
Returns Examples
[
  {
    "attacker": "Flying Yeti",
    "attackerCountry": "CN",
    "attackerCountryAlpha3": "CHN",
    "category": "Domain Resolution",
    "datasetId": "dataset-example-id",
    "date": "2022-04-01T00:00:00Z",
    "event": "An attacker registered the domain domain.com",
    "hasChildren": true,
    "indicator": "domain.com",
    "indicatorType": "domain",
    "indicatorTypeId": 5,
    "killChain": 0,
    "mitreAttack": [
      " "
    ],
    "mitreCapec": [
      " "
    ],
    "numReferenced": 0,
    "numReferences": 0,
    "rawId": "453gw34w3",
    "referenced": [
      " "
    ],
    "referencedIds": [
      0
    ],
    "references": [
      " "
    ],
    "referencesIds": [
      0
    ],
    "tags": [
      "malware"
    ],
    "targetCountry": "US",
    "targetCountryAlpha3": "USA",
    "targetIndustry": "Agriculture",
    "tlp": "amber",
    "uuid": "12345678-1234-1234-1234-1234567890ab",
    "insight": "insight",
    "releasabilityId": "releasabilityId"
  }
]