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

Lists all tags (SoT)

GET/accounts/{account_id}/cloudforce-one/events/tags

Returns all Source-of-Truth tags for an account. Supports legacy free-text search on tag value and categoryUuid exact match, plus a structured filters JSON array for filtering by metadata fields (originCountryISO, actorCategory, motive, priority, etc.). Country values may be passed as alpha-2, alpha-3, name, or common alias.

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
Path ParametersExpand Collapse
account_id: string

Account ID.

Query ParametersExpand Collapse
cache: optional "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.

categoryUuid: optional string
filters: optional array of object { field, op, value }

Structured filters as a JSON array of {field, op, value} objects. Searchable fields: uuid, value, categoryName, description, dateOfDiscovery, tlp, confidence, actorCategory, motive, attributionOrganization, originCountryISO, aliases, externalReferences, opsecLevel, sophisticationLevel, activeDuration, priority, lastSeen, aliasGroupNames. Operators: equals, not, contains, startsWith, endsWith, gt, lt, gte, lte, like, in, find. Use ‘in’ for bulk OR within a single field, e.g. filters=[{“field”:“originCountryISO”,“op”:“in”,“value”:[“IR”,“CN”]}]. Multiple entries are AND-joined. Max 10 entries per request, max 100 values per ‘in’. Per-field notes: uuid accepts only ‘equals’ and ‘in’ (other operators throw ValidationError) — matched against the canonical lowercase storage but callers may pass either case (the server lowercases before comparison); index-backed by the column’s UNIQUE constraint and intended for batched UUID → tag resolution. originCountryISO uses its B-tree index for equals/not/in. priority uses its B-tree index for numeric comparisons. Other string columns (actorCategory, motive, etc.) are case-insensitive and unindexed; current catalog size makes this a non-issue. endsWith and aliasGroupNames contains/like are leading-wildcard scans and slow on large result sets. aliasGroupNames matches on the JSON-encoded text, so substrings can cross alias boundaries (a search for “apt28” will also match “apt280” if both appear in the same tag’s alias list).

field: string

Tag field to search on. Allowed first-class fields: uuid, value, categoryName, description, dateOfDiscovery, tlp, confidence, actorCategory, motive, attributionOrganization, originCountryISO, aliases, externalReferences, opsecLevel, sophisticationLevel, activeDuration, priority, lastSeen, aliasGroupNames. Also supports properties. to filter on custom field values (matches both raw values and annotated {value,confidence,tlp} shapes via COALESCE), and properties..tlp / properties..confidence to filter directly on annotation sub-fields.

op: "equals" or "not" or "gt" or 9 more

Search operator. Use ‘in’ for bulk OR within a single field.

One of the following:
"equals"
"not"
"gt"
"gte"
"lt"
"lte"
"like"
"contains"
"startsWith"
"endsWith"
"in"
"find"
value: optional string or number or array of string or number

Search value. String or number for most operators. Array for ‘in’ (max 100 items).

One of the following:
string
number
array of string or number
One of the following:
string
number
page: optional number
pageSize: optional number
ReturnsExpand Collapse
tags: array of object { uuid, value, activeDuration, 34 more }
uuid: string
value: string
activeDuration: optional string
activeDuration_annotated: optional object { value, tlp }
value: string
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
actorCategory: optional string
actorCategory_annotated: optional object { value, confidence, tlp }
value: string
confidence: optional number
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
aliases: optional array of object { value, confidence, tlp }

Structured aliases ({ value, confidence 1-10, tlp }). Public: returned to all accounts with per-entry TLP filtering (entries with tlp: purple are removed for non-CFONE accounts).

value: string
confidence: optional number
maximum10
minimum1
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
aliasGroupNames: optional array of string
aliasGroupNamesInternal: optional array of string
attributionOrganization: optional string
attributionOrganization_annotated: optional object { value, confidence, tlp }
value: string
confidence: optional number
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
categoryName: optional string
categoryUuid: optional string
confidence: optional number

Overall tag confidence (1-10).

maximum10
minimum1
createdAt: optional string
dateOfDiscovery: optional string
description: optional string
externalReferences: optional array of object { url, description }

Structured external references ({ url, description }). Public: returned to all accounts.

url: string
description: optional string
externalReferences_annotated: optional array of object { value, tlp }
value: string
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
internalAliases: optional array of object { value, confidence, tlp }

Internal structured aliases ({ value, confidence 1-10, tlp }). CFONE-only: never returned to non-CFONE accounts.

value: string
confidence: optional number
maximum10
minimum1
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
internalDescription: optional string
lastSeen: optional string
motive: optional string
motive_annotated: optional object { value, confidence, tlp }
value: string
confidence: optional number
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
opsecLevel: optional string
opsecLevel_annotated: optional object { value, confidence, tlp }
value: string
confidence: optional number
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
originCountryISO: optional string

ISO country code (alpha-2 or alpha-3). Normalized to uppercase on read. Null when stored value is blank/whitespace.

originCountryISO_annotated: optional object { value, confidence, tlp }
value: string
confidence: optional number
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
priority: optional number
priority_annotated: optional object { value, tlp }
value: number
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
properties: optional map[unknown]

Parsed custom field values. Null when the tag has no custom fields.

sophisticationLevel: optional string
sophisticationLevel_annotated: optional object { value, confidence, tlp }
value: string
confidence: optional number
tlp: optional "red" or "amber" or "amber-strict" or 4 more
One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
tlp: optional "red" or "amber" or "amber-strict" or 4 more

Tag-level TLP handling marking.

One of the following:
"red"
"amber"
"amber-strict"
"green"
"clear"
"purple"
"amber+strict"
updatedAt: optional string
version: optional number

Lists all tags (SoT)

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cloudforce-one/events/tags \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
{
  "pagination": {
    "page": 0,
    "pageSize": 0,
    "totalCount": 0,
    "totalPages": 0
  },
  "tags": [
    {
      "uuid": "12345678-1234-1234-1234-1234567890ab",
      "value": "APT28",
      "activeDuration": "activeDuration",
      "activeDuration_annotated": {
        "value": "value",
        "tlp": "red"
      },
      "actorCategory": "actorCategory",
      "actorCategory_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "aliases": [
        {
          "value": "Fancy Bear",
          "confidence": 8,
          "tlp": "amber"
        }
      ],
      "aliasGroupNames": [
        "string"
      ],
      "aliasGroupNamesInternal": [
        "string"
      ],
      "attributionOrganization": "attributionOrganization",
      "attributionOrganization_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "categoryName": "Actor",
      "categoryUuid": "12345678-1234-1234-1234-1234567890ab",
      "confidence": 8,
      "createdAt": "createdAt",
      "dateOfDiscovery": "2024-01-15T00:00:00Z",
      "description": "description",
      "externalReferenceLinks": [
        "string"
      ],
      "externalReferences": [
        {
          "url": "https://example.com/report",
          "description": "Vendor threat report"
        }
      ],
      "externalReferences_annotated": [
        {
          "value": "value",
          "tlp": "red"
        }
      ],
      "internalAliases": [
        {
          "value": "Fancy Bear",
          "confidence": 8,
          "tlp": "amber"
        }
      ],
      "internalDescription": "internalDescription",
      "lastSeen": "lastSeen",
      "motive": "motive",
      "motive_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "opsecLevel": "opsecLevel",
      "opsecLevel_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "originCountryISO": "originCountryISO",
      "originCountryISO_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "priority": 0,
      "priority_annotated": {
        "value": 0,
        "tlp": "red"
      },
      "properties": {
        "foo": "bar"
      },
      "sophisticationLevel": "sophisticationLevel",
      "sophisticationLevel_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "tlp": "amber",
      "updatedAt": "updatedAt",
      "version": 0
    }
  ]
}
Returns Examples
{
  "pagination": {
    "page": 0,
    "pageSize": 0,
    "totalCount": 0,
    "totalPages": 0
  },
  "tags": [
    {
      "uuid": "12345678-1234-1234-1234-1234567890ab",
      "value": "APT28",
      "activeDuration": "activeDuration",
      "activeDuration_annotated": {
        "value": "value",
        "tlp": "red"
      },
      "actorCategory": "actorCategory",
      "actorCategory_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "aliases": [
        {
          "value": "Fancy Bear",
          "confidence": 8,
          "tlp": "amber"
        }
      ],
      "aliasGroupNames": [
        "string"
      ],
      "aliasGroupNamesInternal": [
        "string"
      ],
      "attributionOrganization": "attributionOrganization",
      "attributionOrganization_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "categoryName": "Actor",
      "categoryUuid": "12345678-1234-1234-1234-1234567890ab",
      "confidence": 8,
      "createdAt": "createdAt",
      "dateOfDiscovery": "2024-01-15T00:00:00Z",
      "description": "description",
      "externalReferenceLinks": [
        "string"
      ],
      "externalReferences": [
        {
          "url": "https://example.com/report",
          "description": "Vendor threat report"
        }
      ],
      "externalReferences_annotated": [
        {
          "value": "value",
          "tlp": "red"
        }
      ],
      "internalAliases": [
        {
          "value": "Fancy Bear",
          "confidence": 8,
          "tlp": "amber"
        }
      ],
      "internalDescription": "internalDescription",
      "lastSeen": "lastSeen",
      "motive": "motive",
      "motive_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "opsecLevel": "opsecLevel",
      "opsecLevel_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "originCountryISO": "originCountryISO",
      "originCountryISO_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "priority": 0,
      "priority_annotated": {
        "value": 0,
        "tlp": "red"
      },
      "properties": {
        "foo": "bar"
      },
      "sophisticationLevel": "sophisticationLevel",
      "sophisticationLevel_annotated": {
        "value": "value",
        "confidence": 0,
        "tlp": "red"
      },
      "tlp": "amber",
      "updatedAt": "updatedAt",
      "version": 0
    }
  ]
}