Ransomware Histograms API

The Ransomware Histograms API provides time-based aggregation of ransomware attacks and group activity, allowing you to analyze trends over time.

Get Attacks Histogram

GET/api/v2/histogram/attacks

Retrieve statistics on the number of ransomware attacks per month, providing a time-based view of attack frequency.

Parameters

Name	Type	Required	Description
countries	string	No	Country list following ISO 3166-1 alpha-2 codes (e.g., UK, FR, ES)
gte	string	No	Start date (Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss)
lte	string	No	End date (Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss)

Examples

Shell

curl "https://api.vysion.ai/api/v2/histogram/attacks" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

Python

import requests

headers = {
  'Accept': 'application/json',
  'x-api-key': 'YOUR_API_KEY',
}

r = requests.get('https://api.vysion.ai/api/v2/histogram/attacks', headers=headers)

print(r.json())

Response

{
  "data": {
    "total": 12,
    "hits": [
      {
        "key": "2024-01",
        "key_as_string": "2024-01-01T00:00:00.000Z",
        "doc_count": 234,
        "agg": {
          "buckets": [
            {
              "key": "lockbit",
              "doc_count": 89
            },
            {
              "key": "alphv",
              "doc_count": 67
            },
            {
              "key": "play",
              "doc_count": 78
            }
          ]
        }
      },
      {
        "key": "2024-02",
        "key_as_string": "2024-02-01T00:00:00.000Z",
        "doc_count": 198,
        "agg": {
          "buckets": [
            {
              "key": "lockbit",
              "doc_count": 72
            },
            {
              "key": "alphv",
              "doc_count": 54
            },
            {
              "key": "play",
              "doc_count": 72
            }
          ]
        }
      }
    ]
  },
  "error": null
}

Get Groups Histogram

GET/api/v2/histogram/groups

Retrieve statistics on the number of attacks per ransomware group and month, providing detailed insights into group activity over time.

Parameters

Name	Type	Required	Description
countries	string	No	Country list following ISO 3166-1 alpha-2 codes (e.g., UK, FR, ES)
gte	string	No	Start date (Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss)
lte	string	No	End date (Unix timestamp, YYYY-MM-DD, or YYYY-MM-DDThh:mm:ss)

Examples

Shell

curl "https://api.vysion.ai/api/v2/histogram/groups" \
  --header 'Accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

Python

import requests

headers = {
  'Accept': 'application/json',
  'x-api-key': 'YOUR_API_KEY',
}

r = requests.get('https://api.vysion.ai/api/v2/histogram/groups', headers=headers)

print(r.json())

Response

{
  "data": {
    "total": 12,
    "hits": [
      {
        "key": "2024-01",
        "key_as_string": "2024-01-01T00:00:00.000Z",
        "doc_count": 234,
        "agg": {
          "buckets": [
            {
              "key": "lockbit",
              "doc_count": 89
            },
            {
              "key": "alphv",
              "doc_count": 67
            },
            {
              "key": "play",
              "doc_count": 45
            },
            {
              "key": "cl0p",
              "doc_count": 33
            }
          ]
        }
      },
      {
        "key": "2024-02",
        "key_as_string": "2024-02-01T00:00:00.000Z",
        "doc_count": 198,
        "agg": {
          "buckets": [
            {
              "key": "lockbit",
              "doc_count": 72
            },
            {
              "key": "alphv",
              "doc_count": 54
            },
            {
              "key": "play",
              "doc_count": 42
            },
            {
              "key": "cl0p",
              "doc_count": 30
            }
          ]
        }
      }
    ]
  },
  "error": null
}

Response Schema

Both histogram endpoints return the same response structure:

Histogram Response

Field	Type	Description
data.total	integer	Total number of time buckets
data.hits	array	Array of time bucket objects
data.hits[].key	string	Time bucket key (YYYY-MM format)
data.hits[].key_as_string	string	ISO 8601 formatted date string
data.hits[].doc_count	integer	Total number of attacks in this time period
data.hits[].agg	object	Aggregated statistics for this time period
data.hits[].agg.buckets	array	Array of group statistics
data.hits[].agg.buckets[].key	string	Ransomware group name
data.hits[].agg.buckets[].doc_count	integer	Number of attacks by this group
error	object	Error information (null if successful)

Understanding the Data

Time Buckets

• Each histogram entry represents one month of data
• The key field shows the month in YYYY-MM format
• The key_as_string field provides the full ISO 8601 timestamp
• The doc_count shows the total attacks for that month

Group Aggregations

• The agg.buckets array contains the top ransomware groups for each month
• Groups are typically ordered by attack count (most active first)
• This allows you to see which groups were most active in each time period

Use Cases

• Trend Analysis: Track overall attack volume over time
• Group Activity: Monitor which ransomware groups are most active
• Seasonal Patterns: Identify patterns in attack frequency
• Impact Assessment: Measure the effect of law enforcement actions or security improvements

Error Responses

Histogram endpoints may return these error codes:

Status	Error Code	Description
401	Unauthorized	Invalid or missing API key
422	Unprocessable Entity	Invalid parameters
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Data Visualization Tips

The histogram data is perfect for creating time-series charts:

• Use the key_as_string field for x-axis timestamps
• Use doc_count for total attack volume
• Create stacked charts using the agg.buckets data for group-specific trends
• Consider grouping by quarter or year for longer-term analysis