---
updatedAt: 2026-09-03T10:48:20.000Z
agentTools:
  projectIndex: https://gtidocs.readme.io/llms.txt
---

# Get a global prevalence summary

Retrieve in-the-wild planetary observation and prevalence telemetry for an indicator across Google's enterprise observation mesh.

> 🚧 Special privileges required
>
> Google Insights In-the-Wild Prevalence is only available to users with the Google Threat Intelligence (Google TI) Enterprise or Enterprise Plus licenses.

Returns a [Global Prevalence Summary](https://gtidocs.readme.io/reference/global-prevalence-summary-object) object.

## Examples

### Query prevalence for a file hash using cURL

```bash
curl --request GET \
     --url "https://www.virustotal.com/api/v3/global_prevalence/summarize?entity_value=787e2c94e6d9ce5ec01f5cbe9ee2518431eca8523155526d6dc85934c9c5787c&entity_type=SHA256" \
     --header "accept: application/json" \
     --header "x-apikey: <YOUR_API_KEY>"
```

### Ingest prevalence into a Python SOAR enrichment playbook

```python
import time
import requests

def get_ioc_global_prevalence(entity_value: str, entity_type: str, api_key: str) -> dict:
    """Queries GTI Global Prevalence summary for an indicator."""
    url = "https://www.virustotal.com/api/v3/global_prevalence/summarize"
    headers = {"x-apikey": api_key, "Accept": "application/json"}
    params = {
        "entity_value": entity_value,
        "entity_type": entity_type  # e.g., "SHA256", "IP", "HOSTNAME"
    }
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json().get("data", {}).get("attributes", {})

# Example SOAR Playbook Execution Logic
telemetry = get_ioc_global_prevalence(
    entity_value="203.0.113.55",
    entity_type="IP",
    api_key=SOAR_SECRETS["GTI_API_KEY"]
)

unique_orgs = telemetry.get("customer_count", 0)
raw_sightings = telemetry.get("observation_count", 0)
first_seen_ts = telemetry.get("first_seen_date", 0)
first_industry = telemetry.get("first_seen_industry", "")
last_industry = telemetry.get("last_seen_industry", "")

now = int(time.time())
days_since_first_seen = (now - first_seen_ts) // 86400 if first_seen_ts else 999

# Rule 1: Targeted Vertical Threat (Low org count + peer vertical impact)
if 0 < unique_orgs <= 5 and "FINANCE" in [first_industry, last_industry]:
    alert.add_tag("GTI:Targeted_Vertical_Threat")
    alert.set_severity("CRITICAL")
    alert.increase_risk_score(points=40)
    alert.assign_to("Tier-3 Incident Response")

# Rule 2: High-Volume Shared Infrastructure (Multi-tenant Cloud/CDN IP)
elif unique_orgs > 500 and entity_type == "IP":
    alert.add_tag("GTI:Shared_Infrastructure_Host")
    alert.add_task("Verify SNI / Domain header before applying IP block")

# Rule 3: Emerging In-The-Wild Threat (First observed in enterprise within last 48 hours)
elif unique_orgs > 0 and days_since_first_seen <= 2:
    alert.add_tag("GTI:Emerging_In_The_Wild")
    alert.increase_risk_score(points=25)
```

# OpenAPI definition

```json
{
  "info": {
    "title": "IoC Investigation",
    "version": "3.0"
  },
  "openapi": "3.1.0",
  "tags": [
    {
      "name": "Global Prevalence",
      "description": "In-the-wild planetary telemetry, observation counts, and vertical targeting distributions powered by Google Insights."
    }
  ],
  "paths": {
    "/global_prevalence/summarize": {
      "get": {
        "tags": [
          "Global Prevalence"
        ],
        "summary": "Get global prevalence summary",
        "description": "Retrieve in-the-wild planetary observation and prevalence telemetry for an indicator across Google's enterprise observation mesh.",
        "operationId": "get-global-prevalence-summarize",
        "parameters": [
          {
            "name": "entity_value",
            "in": "query",
            "required": true,
            "description": "The indicator string (e.g. SHA-256, MD5, SHA-1, IPv4/IPv6 address, hostname/domain).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "entity_type",
            "in": "query",
            "required": true,
            "description": "Entity type for the indicator.",
            "schema": {
              "type": "string",
              "enum": [
                "SHA256",
                "MD5",
                "SHA1",
                "HOSTNAME",
                "IP",
                "NETWORK_DNS",
                "VHASH",
                "SSDEEP",
                "SIGNATURE_NAME"
              ]
            }
          },
          {
            "name": "x-apikey",
            "in": "header",
            "required": true,
            "description": "Your API key",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response returning global prevalence summary telemetry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Queried entity value identifier."
                        },
                        "type": {
                          "type": "string",
                          "example": "global_prevalence_summary"
                        },
                        "links": {
                          "type": "object",
                          "properties": {
                            "self": {
                              "type": "string"
                            }
                          }
                        },
                        "attributes": {
                          "type": "object",
                          "properties": {
                            "customer_count": {
                              "type": "integer",
                              "description": "Deduplicated count of distinct enterprise organizations where the indicator was observed."
                            },
                            "observation_count": {
                              "type": "integer",
                              "description": "Total raw volume of observation events recorded across Google observation networks."
                            },
                            "first_seen_date": {
                              "type": "integer",
                              "description": "UTC timestamp (seconds since Unix epoch) of first in-the-wild observation."
                            },
                            "last_seen_date": {
                              "type": "integer",
                              "description": "UTC timestamp (seconds since Unix epoch) of most recent in-the-wild observation."
                            },
                            "first_seen_industry": {
                              "type": "string",
                              "description": "Industry vertical where the indicator was first observed."
                            },
                            "last_seen_industry": {
                              "type": "string",
                              "description": "Industry vertical of the most recent in-the-wild observation."
                            },
                            "first_seen_region": {
                              "type": "string",
                              "description": "Geographic region where the indicator was first observed."
                            },
                            "last_seen_region": {
                              "type": "string",
                              "description": "Geographic region of the most recent in-the-wild observation."
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Missing or invalid required query parameters (entity_value or entity_type)."
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key."
          },
          "403": {
            "description": "Forbidden - Insufficient license privileges. Requires GTI Enterprise or Enterprise Plus subscription."
          }
        }
      }
    }
  },
  "security": [],
  "servers": [
    {
      "url": "https://www.virustotal.com/api/v3"
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "headers": [],
    "proxy-enabled": false,
    "samples-enabled": true
  }
}
```