Overview
The Dash Reports API provides access to comprehensive threat intelligence and effectiveness reporting data from the Proofpoint Threat Protection platform. This API enables administrators to retrieve executive summary reports and effectiveness metrics programmatically for integration with custom dashboards, reporting tools, and analytics platforms.
Getting Started
Follow these steps to make your first API call to the Dash Reports API:
Step 1: Obtain API Credentials
Credentials are provisioned through Cloud Admin UI (Threat Protection Page) > Settings > API Key Management > Threat Protection tab (generate and manage keys).
Navigate to the API Key Management section and click + Create New to generate a new API key and secret for the Threat Protection API.
Step 2: Generate Authentication Token
Use the key and secret generated from the Admin Portal (See API Key Management) to generate an authentication token. The token is valid for 1 hour.
Example request with curl:
#!/bin/bash
CONTENT_TYPE="Content-Type: application/x-www-form-urlencoded"
URL="https://auth.proofpoint.com/v1/token"
BODY="grant_type=client_credentials&client_id=<KEY>&client_secret=<SECRET>"
curl -s -X POST -d"$BODY" -H "$CONTENT_TYPE" "$URL"
Example JSON response:
{
"access_token": "<GENERATED AUTH TOKEN>",
"token_type": "Bearer",
"expires_in": 3600
}
Use the access_token value from the response as your Bearer token in subsequent API calls.
Step 3: Make Your First API Call
Here's an example of calling the Inbound Protection Overview endpoint:
# Set your authentication token
AUTH_TOKEN="your_bearer_token_here"
# Define the time range (must be in UTC)
START_DATE="2024-01-01T00:00:00Z"
END_DATE="2024-01-31T23:59:59Z"
# Make the API request
curl -X GET "https://threatprotection-api.proofpoint.com/api
/v1/dash/reports/executive-summary/inbound-protection-overview?start=${START_DATE}&end=${END_DATE}" \
-H "Authorization: Bearer ${AUTH_TOKEN}" \
-H "Content-Type: application/json"
Step 4: Parse the Response
A successful response (HTTP 200) returns JSON data:
{
"preDeliveryProtectedMessages": 15234,
"postDeliveryProtectedMessages": 2341,
"potentiallyExposedMessages": 456,
"preDeliveryProtectedMessagesPctTotal": 0.845,
"postDeliveryProtectedMessagesPctTotal": 0.13,
"potentiallyExposedMessagesPctTotal": 0.025,
"overallInboundProtection": 0.975
}
API Features
General Service Notes
- All timestamps must be provided in ISO 8601 format in UTC (e.g., 2024-01-27T12:00:00Z or 2024-01-01T00:00:00.000Z)
- The API returns data in JSON format
- The API enforces pagination and response size limits that align with the platform's user interface.
- Authentication is required for all endpoints using Bearer token
- Requests are rate-limited to prevent abuse.
Security
Each request must use:
- SSL/TLS (HTTPS)
- Bearer token authentication via the Authorization header
- HTTP GET method
API Key Management:
Credentials are provisioned through Cloud Admin UI > Settings > API Key Management > Threat Protection tab. Navigate to this section and click + Create New to generate a new API key and secret.
Token Generation:
Use the key and secret to generate an authentication token. The token is valid for 1 hour.
#!/bin/bash
CONTENT_TYPE="Content-Type: application/x-www-form-urlencoded"
URL="https://auth.proofpoint.com/v1/token"
BODY="grant_type=client_credentials&client_id=<KEY>&client_secret=<SECRET>"
curl -s -X POST -d"$BODY" -H "$CONTENT_TYPE" "$URL"
Example response:
{
"access_token": "<GENERATED AUTH TOKEN>",
"token_type": "Bearer",
"expires_in": 3600
}
Using the Token:
Include the access_token in the Authorization header for all API requests:
Authorization: Bearer <your_token>
Standard Responses
Requests to the endpoints can produce a response with a variety of HTTP status codes. The following table describes the scenarios in which these codes can be produced:
| Status Code |
Description |
| 200 |
Success - The request was processed successfully and data is returned |
| 400 |
Bad Request - The request is missing a mandatory parameter or contains incorrectly formatted data |
| 401 |
Unauthorized - There is no authorization information included in the request or the authorization information is incorrect |
| 403 |
Forbidden - The user is authenticated but is not authorized to access data for the given customer |
| 429 |
Too Many Requests - The user has exceeded the rate limit and has been throttled |
| 500 |
Internal Server Error - The service has encountered an unexpected situation |
Rate Limits for Dashboard Reports APIs — Customer Guide
How Rate Limiting Works
The Dashboard Reports APIs have rate limiting to ensure fair usage and system stability.
Rate Limit Summary
| Limit Type |
What It Tracks |
Limit |
Reset Period |
| Per API Key E |
Total calls using a particular API Key |
10 requests |
Every minute |
| Per Report Section |
Calls to a specific report category (e.g., Executive Summary) |
20 requests |
Every day |
When You'll Get HTTP 429 (Too Many Requests)
You'll receive a 429 error if you exceed any of these limits:
- More than 10 requests per minute per API Key
- More than 20 requests per day to a specific report section
Report Sections (each has its own daily limit)
- Executive Summary APIs
- Effectiveness Report APIs
- Threat Landscape APIs
- People Report APIs
- Organization Report APIs
- Threat Objectives APIs
- BEC Report APIs
Example Scenario
If you call the Executive Summary APIs 20 times in one day, your 21st call to any Executive Summary endpoint will return 429. However, you can still call Effectiveness or People APIs (until you hit their limits).
Available Endpoints
All endpoints are available on the base path /api/v1/dash/reports
Executive Summary Endpoints
GET /executive-summary/inbound-Email-protection-Breakdown
Retrieves breakdown of inbound email protection metrics for the specified cluster and time range. This endpoint mirrors the Dashboard › Executive Summary › Inbound Email Protection Breakdown card.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format (e.g., 2024-01-01T00:00:00.000Z) |
Must be valid ISO 8601 format in UTC with milliseconds |
| end |
String |
End time for the reporting period in ISO 8601 UTC format (e.g., 2024-01-31T23:59:59.000Z) |
Must be valid ISO 8601 format in UTC with milliseconds |
| clusterId |
String |
Cluster ID for the request |
Required |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| clusterId |
Missing |
ClusterId is required. |
| start |
Invalid format |
Invalid startDate format. Expected ISO format (e.g., 2023-01-01T00:00:00.000Z) |
| end |
Invalid format |
Invalid endDate format. Expected ISO format (e.g., 2023-01-01T00:00:00.000Z) |
| start |
Date too old |
Start date cannot be older than 90 days from today |
Sample 200 Response:
{
"total": [
{
"key": "received",
"count": 100000
},
{
"key": "delivered",
"count": 85000
},
{
"key": "blocked",
"count": 15000
},
{
"key": "reputation",
"count": 5000
},
{
"key": "malware",
"count": 178
},
{
"key": "phish",
"count": 168
},
{
"key": "impostor",
"count": 47
}
]
}
Response Fields:
| Field |
Type |
Description |
| total |
Array |
Array of message category counts |
| total[].key |
String |
Category key (received, delivered, blocked, reputation, malware, phish, impostor) |
| total[].count |
Long |
Count of messages in this category |
Category Keys:
| Key |
Description |
| received |
Total number of inbound messages received |
| delivered |
Number of messages delivered to recipients |
| blocked |
Number of messages blocked |
| reputation |
Number of messages blocked due to reputation |
| malware |
Number of messages containing malware |
| phish |
Number of phishing messages detected |
| impostor |
Number of impostor/BEC messages detected |
UI to API Field Mapping:
| UI Field |
API Field(s) |
| Total inbound |
received + reputation |
| Sender intel |
reputation |
| Commodity Threats |
blocked |
| Advanced Malware Threats |
malware |
| Phishing Threats |
phish |
| BEC Threats |
impostor |
| Delivered |
delivered |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/executive-summary/inbound-email-protection-breakdown?start=2024-01-01T00:00:00.000Z&end=2024-01-31T23:59:59.000Z&clusterId=YOUR_CLUSTER_ID" -H "Authorization: Bearer YOUR_TOKEN"
GET /executive-summary/Inbound-Protection-Overview
Retrieves an overview of inbound protection metrics including messages processed, threats detected, and protection effectiveness.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format (e.g., 2024-01-01T00:00:00Z) |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format (e.g., 2024-01-31T23:59:59Z) |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"preDeliveryProtectedMessages": 15234,
"postDeliveryProtectedMessages": 2341,
"potentiallyExposedMessages": 456,
"preDeliveryProtectedMessagesPctTotal": 0.845,
"postDeliveryProtectedMessagesPctTotal": 0.13,
"potentiallyExposedMessagesPctTotal": 0.025,
"overallInboundProtection": 0.975
}
Response Fields:
| Field |
Type |
Description |
| preDeliveryProtectedMessages |
Long |
Number of messages protected before delivery (blocked/quarantined) |
| postDeliveryProtectedMessages |
Long |
Number of messages protected after delivery (remediated) |
| potentiallyExposedMessages |
Long |
Number of messages that were potentially exposed to users |
| preDeliveryProtectedMessagesPctTotal |
Double |
Percentage of pre-delivery protected messages relative to total |
| postDeliveryProtectedMessagesPctTotal |
Double |
Percentage of post-delivery protected messages relative to total |
| potentiallyExposedMessagesPctTotal |
Double |
Percentage of potentially exposed messages relative to total |
| overallInboundProtection |
Double |
Overall inbound protection rate (1.0 - potentiallyExposedMessagesPctTotal) |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/executive-summary/inbound-protection-overview?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /executive-summary/advanced-threat-detection-messages-protected
Retrieves detailed metrics about messages protected by advanced threat detection, with breakdowns by threat type or other dimensions.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| breakdown |
String |
by-threat-type |
Breakdown dimension for the data |
Valid values: by-threat-type, by-threat-category |
| type |
String |
- |
Message type filter (when breakdown=by-threat-type) |
Valid values: ALL, URL, ATTACHMENT, MESSAGE, HYBRID |
| category |
String |
- |
Message category filter (when breakdown=by-threat-category) |
Valid values: MALWARE, PHISHING, SPAM, BEC, TOAD |
| groupBy |
String |
DAY |
Time grouping for results |
Valid values: DAY, WEEK, MONTH, QUARTER. Allowed values depend on date range: 0-13 days: DAY only; 14-30 days: DAY, WEEK; 31-89 days: DAY, WEEK, MONTH; 90 days: WEEK, MONTH, QUARTER |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| breakdown |
Invalid value |
Unsupported breakdown type '{value}'. Supported types: [by-threat-type, by-threat-category] |
| type |
Invalid value |
Invalid type parameter. Allowed values: ALL, ATTACHMENT, URL, MESSAGE, HYBRID |
| category |
Invalid value |
Invalid category parameter. Allowed values: MALWARE, PHISHING, SPAM, BEC, TOAD |
| type/category |
Both provided |
Both type and category cannot be passed. Please ensure to pass either based on the breakdown. |
| groupBy |
Invalid value |
Invalid groupBy value: {value}. Please use one of: DAY, WEEK, MONTH |
| groupBy |
Invalid for date range (0-13 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges up to 13 days, only DAY grouping is allowed. |
| groupBy |
Invalid for date range (14-30 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 14 days and up to 30 days, allowed dateGrouping values are: DAY, WEEK. |
| groupBy |
Invalid for date range (31-89 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 30 days and up to 89 days, allowed dateGrouping values are: DAY, WEEK, MONTH. |
| groupBy |
Invalid for date range (90 days) |
Invalid groupBy '{value}' for the specified date range of 90 days. For 90 day ranges, allowed dateGrouping values are: WEEK, MONTH, QUARTER. |
Sample 200 Response:
{
"messagesProtectedTrend": {
"breakdownName": "by-threat-type",
"groupByName": "ALL-MESSAGES",
"messagesProtectedByDay": {
"2024-01-01": {
"maliciousMessages": 1000,
"totalProtectedPercent": 0.98,
"preDeliveryProtectedMessages": 900,
"postDeliveryProtectedMessages": 80,
"postDeliveryTRQuarantinesUnRead": 10,
"postDeliveryURLRewrittenNoPermittedClicks": 5,
"potentiallyExposedMessages": 20,
"potentiallyExposedWithAttachments": 5,
"potentiallyExposedWithTextThreats": 3,
"potentiallyExposedWithPermittedClicks": 8,
"potentiallyExposedWithNonRewrittenURLs": 4
}
},
"total": {
"maliciousMessages": 5000,
"totalProtectedPercent": 0.98,
"preDeliveryProtectedMessages": 4500,
"postDeliveryProtectedMessages": 400,
"postDeliveryTRQuarantinesUnRead": 50,
"postDeliveryURLRewrittenNoPermittedClicks": 25,
"potentiallyExposedMessages": 100,
"potentiallyExposedWithAttachments": 25,
"potentiallyExposedWithTextThreats": 15,
"potentiallyExposedWithPermittedClicks": 40,
"potentiallyExposedWithNonRewrittenURLs": 20
}
},
"messagesProtectedInsights": {
"totalPotentiallyExposedMessages": 100,
"totalPotentiallyExposedCampaigns": {},
"topTwoPotentiallyExposedObjectives": [],
"totalPotentiallyExposedAPTCampaigns": 0,
"topTwoPotentiallyExposedActors": [],
"totalPotentiallyExposedVIP": [],
"totalPotentiallyExposedVAP": [],
"totalPotentiallyExposedCustomerVerticalCampaigns": {},
"totalPotentiallyExposedCompanyTrafficCampaigns": 0,
"totalPotentiallyExposedNonRewrittenUrls": 20
}
}
Response Fields:
| Field |
Type |
Description |
| messagesProtectedTrend |
Object |
Messages protected trend data |
| messagesProtectedTrend.breakdownName |
String |
Breakdown type name (by-threat-type or by-threat-category) |
| messagesProtectedTrend.groupByName |
String |
Group by name (ALL-MESSAGES, DAY, WEEK, MONTH, QUARTER) |
| messagesProtectedTrend.messagesProtectedByDay |
Object |
Map of date-keyed statistics |
| messagesProtectedTrend.total |
Object |
Aggregated total statistics |
| messagesProtectedTrend.total.maliciousMessages |
Long |
Total number of malicious messages |
| messagesProtectedTrend.total.totalProtectedPercent |
Double |
Percentage of messages that were protected |
| messagesProtectedTrend.total.preDeliveryProtectedMessages |
Long |
Messages protected before delivery |
| messagesProtectedTrend.total.postDeliveryProtectedMessages |
Long |
Messages protected after delivery |
| messagesProtectedTrend.total.postDeliveryTRQuarantinesUnRead |
Long |
Post-delivery TR quarantines unread |
| messagesProtectedTrend.total.postDeliveryURLRewrittenNoPermittedClicks |
Long |
Post-delivery URL rewritten with no permitted clicks |
| messagesProtectedTrend.total.potentiallyExposedMessages |
Long |
Messages that were potentially exposed |
| messagesProtectedTrend.total.potentiallyExposedWithAttachments |
Long |
Potentially exposed with attachments |
| messagesProtectedTrend.total.potentiallyExposedWithTextThreats |
Long |
Potentially exposed with text threats |
| messagesProtectedTrend.total.potentiallyExposedWithPermittedClicks |
Long |
Potentially exposed with permitted clicks |
| messagesProtectedTrend.total.potentiallyExposedWithNonRewrittenURLs |
Long |
Potentially exposed with non-rewritten URLs |
| messagesProtectedInsights |
Object |
Insights about potentially exposed messages |
| messagesProtectedInsights.totalPotentiallyExposedMessages |
Integer |
Total count of potentially exposed messages |
| messagesProtectedInsights.totalPotentiallyExposedCampaigns |
Object |
Map of campaign names to counts |
| messagesProtectedInsights.topTwoPotentiallyExposedObjectives |
Array |
Top two objectives for potentially exposed messages |
| messagesProtectedInsights.totalPotentiallyExposedAPTCampaigns |
Integer |
Count of APT campaigns with potentially exposed messages |
| messagesProtectedInsights.topTwoPotentiallyExposedActors |
Array |
Top two actors for potentially exposed messages |
| messagesProtectedInsights.totalPotentiallyExposedVIP |
Array |
List of VIP users with potentially exposed messages |
| messagesProtectedInsights.totalPotentiallyExposedVAP |
Array |
List of VAP users with potentially exposed messages |
| messagesProtectedInsights.totalPotentiallyExposedCustomerVerticalCampaigns |
Object |
Map of vertical campaigns to counts |
| messagesProtectedInsights.totalPotentiallyExposedCompanyTrafficCampaigns |
Integer |
Count of company traffic campaigns with potentially exposed messages |
| messagesProtectedInsights.totalPotentiallyExposedNonRewrittenUrls |
Integer |
Count of non-rewritten URLs in potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/executive-summary/advanced-threat-detection-messages-protected?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&breakdown=by-threat-type&groupBy=DAY" -H "Authorization: Bearer YOUR_TOKEN"
GET /executive-summary/threat-categories
Retrieves a breakdown of threats by category for the specified time period.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"totalVolume": 5000,
"threatCategories": [
{
"name": "Malware",
"volume": 2500,
"percentage": 0.5
},
{
"name": "Phishing",
"volume": 1500,
"percentage": 0.3
},
{
"name": "BEC",
"volume": 1000,
"percentage": 0.2
}
]
}
Response Fields:
| Field |
Type |
Description |
| totalVolume |
Long |
Total volume of threats across all categories |
| threatCategories |
Array |
List of threat categories with their statistics |
| threatCategories[].name |
String |
Name of the threat category (e.g., Malware, Phishing, Spam, Impostor) |
| threatCategories[].volume |
Long |
Number of threats in this category |
| threatCategories[].percentage |
Double |
Percentage of total volume for this category |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/executive-summary/threat-categories?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /executive-summary/threat-landscape-effectiveness
Retrieves threat landscape and effectiveness metrics with various breakdown options.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| breakDownBy |
String |
threat-objectives |
Breakdown dimension |
Valid values: actors, malware, families, techniques, threat-objectives |
| messageStatus |
String |
volume |
Message status filter |
Valid values: volume, delivered, clicks |
| count |
String |
top5 |
Number of results to return |
Valid values: top5, top10 |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| breakDownBy |
Invalid value |
Invalid breakDownBy parameter. Allowed values: actors, malware, families, techniques, threat-objectives |
| messageStatus |
Invalid value |
Invalid messageStatus parameter. Allowed values: volume, delivered, clicks |
| count |
Invalid value |
Invalid count parameter. Allowed values: top5, top10 |
Sample 200 Response:
{
"breakDownBy": "actors",
"messageStatus": "volume",
"resources": [
{
"name": "TA505",
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"name": "APT29",
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| breakDownBy |
String |
The breakdown dimension used for the results |
| messageStatus |
String |
The message status filter applied |
| resources |
Array |
List of threat resources with protection metrics |
| resources[].name |
String |
Name of the threat actor, malware, or objective |
| resources[].total |
Integer |
Total number of messages associated with this resource |
| resources[].preDeliveryProtected |
Integer |
Messages blocked before delivery |
| resources[].postDeliveryProtected |
Integer |
Messages quarantined after delivery |
| resources[].potentiallyExposed |
Integer |
Messages that may have been accessed by users |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/executive-summary/threat-landscape-effectiveness?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&breakDownBy=threat-objectives&count=top5" -H "Authorization: Bearer YOUR_TOKEN"
GET /executive-summary/very-attacked-people
Retrieves information about the most targeted individuals in the organization (Very Attacked People).
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"topVeryAttackedPeople": [
{
"name": "John Doe",
"attackIndex": 95
},
{
"name": "Jane Smith",
"attackIndex": 87
}
]
}
Response Fields:
| Field |
Type |
Description |
| topVeryAttackedPeople |
Array |
List of top very attacked people |
| topVeryAttackedPeople[].name |
String |
Name of the person |
| topVeryAttackedPeople[].attackIndex |
Long |
Attack index score for the person |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/executive-summary/very-attacked-people?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /executive-summary/industry-comparison
Retrieves industry comparison metrics to compare your company's data (quarterly) with up to 3 industries.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| startMonth |
String |
Starting month for the comparison period in ISO 8601 format (e.g., 2026-01) |
Must be valid ISO 8601 year-month format |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| industries |
List<String> |
Customer's default |
List of industry verticals to compare against. Maximum 3 verticals allowed. |
Valid industry names. Use the key values from the GET /industries endpoint here: Valid industry names |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| startMonth |
Invalid format/range Valid Range : last 13 months to 3 months ago |
Invalid query param startMonth. Please use format YYYY-MM within the allowed range. |
| industries |
Too many values |
Too many industries specified: {count}. Maximum allowed is 3 industries. |
| industries |
Invalid value |
Invalid industries parameter: {value}. Please use valid industry names. Refer to Valid industry names. |
Sample 200 Response:
{
"customer": {
"attackIndex": 85,
"families": [
{
"name": "Emotet",
"score": 45,
"percentContribution": 0.5294
}
]
},
"verticals": [
{
"name": "TECHNOLOGY",
"attackIndex": 75,
"families": [
{
"name": "Trickbot",
"score": 35,
"percentContribution": 0.4667
}
]
}
]
}
Response Fields:
| Field |
Type |
Description |
| customer |
Object (optional) |
Customer's attack index data |
| customer.attackIndex |
Integer |
Customer's overall attack index score |
| customer.families |
Array |
List of threat families contributing to the attack index |
| customer.families[].name |
String |
Name of the threat family |
| customer.families[].score |
Integer |
Score for this threat family |
| customer.families[].percentContribution |
Double |
Percentage contribution of this family to the total attack index |
| verticals |
Array (optional) |
List of vertical/industry attack indices for comparison |
| verticals[].name |
String |
Name of the vertical/industry |
| verticals[].attackIndex |
Integer |
Attack index for this vertical |
| verticals[].families |
Array |
List of threat families for this vertical |
| verticals[].families[].name |
String |
Name of the threat family |
| verticals[].families[].score |
Integer |
Score for this threat family |
| verticals[].families[].percentContribution |
Double |
Percentage contribution of this family to the vertical's attack index |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/executive-summary/industry-comparison?startMonth=2026-02&industries=TECHNOLOGY" -H "Authorization: Bearer YOUR_TOKEN"
GET /executive-summary/top-clickers
Retrieves information about users who have clicked on the most malicious links (Top Clickers).
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"recipients": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"recipient": "user@example.com",
"attackIndex": 85.5,
"blockedClicks": 12,
"permittedClicks": 3,
"vip": true
}
]
}
Response Fields:
| Field |
Type |
Description |
| recipients |
Array |
List of top clickers data |
| recipients[].id |
UUID |
Unique identifier for the user |
| recipients[].recipient |
String |
Email address of the recipient |
| recipients[].attackIndex |
Float |
Attack index score for the user (0-100) |
| recipients[].blockedClicks |
Long |
Number of clicks that were blocked |
| recipients[].permittedClicks |
Long |
Number of clicks that were permitted |
| recipients[].vip |
Boolean |
Whether the user is marked as VIP |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/executive-summary/top-clickers?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
Effectiveness Reports Endpoints
GET /effectiveness-reports/messages-protected
Retrieves metrics about messages protected with optional breakdown by threat type or other dimensions.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| breakdown |
String |
by-threat-type |
Breakdown dimension for the data |
Valid values: by-threat-type, by-threat-category |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| breakdown |
Invalid value |
Unsupported breakdown type '{value}'. Supported types: [by-threat-type, by-threat-category] |
Sample 200 Response:
{
"statsByBreakdownValue": [
{
"breakdownName": "url",
"preDeliveryProtectedMessages": 5000,
"postDeliveryProtectedMessages": 1200,
"potentiallyExposedMessages": 300,
"messagesWithNonRewrittenUrls": 50,
"messagesWithPermittedClicks": 25,
"breakdownProtectedMessagesTotal": 6200,
"breakdownMessagesTotal": 6500,
"breakdownMessagesProtectionPct": 0.954
},
{
"breakdownName": "attachment",
"preDeliveryProtectedMessages": 3000,
"postDeliveryProtectedMessages": 800,
"potentiallyExposedMessages": 150,
"messagesWithNonRewrittenUrls": null,
"messagesWithPermittedClicks": null,
"breakdownProtectedMessagesTotal": 3800,
"breakdownMessagesTotal": 3950,
"breakdownMessagesProtectionPct": 0.962
}
],
"totals": {
"preDeliveryProtectedMessages": 8000,
"postDeliveryProtectedMessages": 2000,
"potentiallyExposedMessages": 450,
"overallMessagesProtectionPctTotal": 0.957
}
}
Response Fields:
| Field |
Type |
Description |
| statsByBreakdownValue |
Array |
Statistics broken down by breakdown value (e.g., url, attachment, messageText) |
| statsByBreakdownValue[].breakdownName |
String |
The breakdown name (e.g., "url", "attachment", "messageText") |
| statsByBreakdownValue[].preDeliveryProtectedMessages |
Long |
Number of messages protected before delivery |
| statsByBreakdownValue[].postDeliveryProtectedMessages |
Long |
Number of messages protected after delivery |
| statsByBreakdownValue[].potentiallyExposedMessages |
Long |
Number of messages that were potentially exposed |
| statsByBreakdownValue[].messagesWithNonRewrittenUrls |
Long (nullable) |
Number of messages with non-rewritten URLs (URL breakdown only) |
| statsByBreakdownValue[].messagesWithPermittedClicks |
Long (nullable) |
Number of messages with permitted clicks (URL breakdown only) |
| statsByBreakdownValue[].breakdownProtectedMessagesTotal |
Long |
Total protected messages for this breakdown |
| statsByBreakdownValue[].breakdownMessagesTotal |
Long |
Total messages for this breakdown |
| statsByBreakdownValue[].breakdownMessagesProtectionPct |
Double |
Percentage of messages protected for this breakdown |
| totals |
Object |
Overall totals across all breakdown values |
| totals.preDeliveryProtectedMessages |
Long |
Total messages protected before delivery |
| totals.postDeliveryProtectedMessages |
Long |
Total messages protected after delivery |
| totals.potentiallyExposedMessages |
Long |
Total messages potentially exposed |
| totals.overallMessagesProtectionPctTotal |
Double |
Overall percentage of messages protected |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/effectiveness-reports/messages-protected?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&breakdown=by-threat-type" -H "Authorization: Bearer YOUR_TOKEN"
GET /effectiveness-reports/messages-protected-trend
Retrieves trend data for messages protected over time with various filtering and grouping options.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| breakdown |
String |
by-threat-type |
Breakdown dimension for the data |
Valid values: by-threat-type, by-threat-category |
| type |
String |
- |
Message type filter (when breakdown=by-threat-type) |
Valid values: ALL, URL, ATTACHMENT, MESSAGE, HYBRID |
| category |
String |
- |
Message category filter (when breakdown=by-threat-category) |
Valid values: MALWARE, PHISHING, SPAM,, BEC, TOAD |
| groupBy |
String |
DAY |
Time grouping for results |
Valid values: DAY, WEEK, MONTH, QUARTER. Allowed values depend on data range: 0-13 days: DAY only; 14-30 days: DAY, WEEK; 31-89 days: DAY, WEEK, MONTH; 90 days: WEEK, MONTH, QUARTER |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| breakdown |
Invalid value |
Invalid breakdown type '{value}'. Supported types: [by-threat-type, by-threat-category] |
| type |
Invalid value |
Invalid type parameter. Allowed values: ALL. ATTACHMENT, URL, MESSAGE, HYBRID |
| category |
Invalid Value |
Invalid category parameter. Allowed values: MALWARE, PHISHING, SPAM, BEC, TOAD |
| groupBy |
Invalid value |
Invalid groupBy value: {value}. Please use one of: DAY, WEEK, MONTH |
| groupBy |
Invalid for date range (0-13 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges up to 13 days, only DAY grouping is allowed. |
| groupBy |
Invalid for date range (14-30 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 14 days and up to 30 days, allowed dateGrouping values are: DAY, WEEK. |
| groupBy |
Invalid for date range (31-89 days) |
Invali groupBy '{value}' for the specified date range of [days} days. For date ranges greater than 30 days and up to 89 days, allowed dateGrouping values are: DAY, WEEK, MONTH. |
| groupBy |
Invalid for date range (90 days) |
Invalid groupBy '{value}' for the specified date range of 90 days. For 90 day ranges, allowed dateGrouping values are: WEEK, MONTH, QUARTER. |
Sample 200 Response:
{
"breakdownName": "by-threat-type",
"groupByName": "WEEK",
"messagesProtectedByDay": {
"2024-01-01": {
"maliciousMessages": 1000,
"totalProtectedPercent": 0.98,
"preDeliveryProtectedMessages": 900,
"postDeliveryProtectedMessages": 80,
"postDeliveryTRQuarantinesUnRead": 10,
"postDeliveryURLRewrittenNoPermittedClicks": 5,
"potentiallyExposedMessages": 20,
"potentiallyExposedWithAttachments": 5,
"potentiallyExposedWithTextThreats": 3,
"potentiallyExposedWithPermittedClicks": 8,
"potentiallyExposedWithNonRewrittenURLs": 4
}
},
"total": {
"maliciousMessages": 5000,
"totalProtectedPercent": 0.98,
"preDeliveryProtectedMessages": 4500,
"postDeliveryProtectedMessages": 400,
"postDeliveryTRQuarantinesUnRead": 50,
"postDeliveryURLRewrittenNoPermittedClicks": 25,
"potentiallyExposedMessages": 100,
"potntiallyExposedWithAttachments": 25,
"potentiallyExposedWithTextThreats": 15,
"potentiallyExposedWithPermittedClicks": 40,
"potentiallyExposedWithNonRewrittenURLs": 20
}
}
Response Fields:
| Field |
Type |
Description |
| breakdownName |
String |
Breakdown type name (by-threat-type or by-threat-categroty) |
| groupByName |
String |
Group by name (DAY, WEEK, MONTH, QUARTER) |
| messagesProtectedByDay |
Object |
Map of date-keyed statistics |
| messagesProtectedByDay[date].maliciousMessages |
Long |
Number of malicious messages |
| messagesProtectedByDay[date].totalProtectedPercent |
Double |
Percentage of messages protected |
| messagesProtectedByDay[date].preDeliveryProtectedMessages |
Long |
Messages protected before delivery |
| messagesProtectedByDay[date].postDeliveryProtectedMessages |
Long |
Messages protected after delivery |
| messagesProtectedByDay[date].postDeliveryTRQuarantinesUnRead |
Long |
Post-delivery TR quarantines unread |
| messagesProtectedByDay[date].postDeliveryURLRewrittenNoPermittedClicks |
Long |
Post-delivery URL rewritten with no permitted clicks |
| messagesProtectedByDay[date].potentiallyExposedMessages |
Long |
Potentially exposed messages |
| messagesProtectedByDay[date].potentiallyExposedWithAttachments |
Long |
Potentially exposed with attachments |
| messagesProtectedByDay[date].potentiallyExposedWithTextThreats |
Long |
Potentially exposed with text threats |
| messagesProtectedByDay[date].potentiallyExposedWithPermittedClicks |
Long |
Potentially exposed with permitted clicks |
| messagesProtectedByDay[date],potentiallyExposedWithNonRewrittenURLs |
Long |
Potentially exposed with non-rewritten URLs |
| total |
Object |
Aggregated total statistics (same fields as messagesProtectedByDay[date]) |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/effectiveness-reports/messages-protected-trend?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&groupBy=WEEK" -H "Authorization: Bearer YOUR_TOKEN"
GET /effectiveness-reports/threat-response-quarantines
Retrieves metrics about messages quarantined by Threat Response actions.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| groupBy |
String |
WEEK |
Time grouping for results |
Valid values: DAY, WEEK, MONTH |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| groupBy |
Invalid value |
Invalid groupBy value: {value}. Please use one of: DAY, WEEK, MONTH |
Sample 200 Response:
{
"data": {
"2024-01-01": {
"numberOfTapMessages": 100,
"numberOfMessageCopiesQuarantinedUnread": 80,
"numberOfMessageCopiesQuarantinedRead": 15,
"numberOfMessageCopiesSkippedSkiplisted": 3,
"numberOfMessageCopiesSkippedExternal": 2
}
},
"total": {
"numberOfTapMessages": 100,
"numberOfMessageCopiesQuarantinedUnread": 80,
"numberOfMessageCopiesQuarantinedRead": 15,
"numberOfMessageCopiesSkippedSkiplisted": 3,
"numberOfMessageCopiesSkippedExternal": 2
}
}
Response Fields:
| Field |
Type |
Description |
| data |
Object |
Map of date-keyed quarantine statistics |
| data[date] |
Object |
Quarantine statistics for a specific date |
| data[date].numberOfTapMessages |
Integer |
Number of TAP (Targeted Attack Protection) messages |
| data[date].numberOfMessageCopiesQuarantinedUnread |
Integer |
Number of message copies quarantined that were unread |
| data[date].numberOfMessageCopiesQuarantinedRead |
Integer |
Number of message copies quarantined that were already read |
| data[date].numberOfMessageCopiesSkippedSkiplisted |
Integer |
Number of message copies skipped due to skiplist |
| data[date].numberOfMessageCopiesSkippedExternal |
Integer |
Number of message copies skipped due to external recipients |
| total |
Object |
Aggregated totals across all dates |
| total.numberOfTapMessages |
Integer |
Total TAP messages across all dates |
| total.numberOfMessageCopiesQuarantinedUnread |
Integer |
Total unread quarantined message copies |
| total.numberOfMessageCopiesQuarantinedRead |
Integer |
Total read quarantined message copies |
| total.numberOfMessageCopiesSkippedSkiplisted |
Integer |
Total skiplisted message copies |
| total.numberOfMessageCopiesSkippedExternal |
Integer |
Total external skipped message copies |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/effectiveness-reports/threat-response-quarantines?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&groupBy=WEEK" -H "Authorization: Bearer YOUR_TOKEN"
GET /effectiveness-reports/clicks-protected
Retrieves metrics about malicious clicks that were blocked or protected.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| groupBy |
String |
WEEK |
Time grouping for results |
Valid values: DAY, WEEK, MONTH |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| groupBy |
Invalid value |
Invalid groupBy value: {value}. Please use one of: DAY, WEEK, MONTH |
Sample 200 Response:
{
"grouping": {
"type": "WEEK",
"data": [
{
"period": "2024-01-01",
"clicks": 185,
"protectedPercentage": 94.59,
"blocked": 150,
"isolated": 25,
"permitted": 10
}
]
},
"totals": {
"totalClicks": 185,
"protectedPercentage": 94.59,
"blocked": 150,
"isolated": 25,
"permitted": 10
}
}
Response Fields:
| Field |
Type |
Description |
| grouping |
Object |
Grouping information for the data |
| grouping.type |
String |
Type of grouping (DAY, WEEK, MONTH) |
| grouping.data |
Array |
List of period data |
| grouping.data[].period |
String |
Period date string |
| grouping.data[].clicks |
Long |
Total clicks in this period |
| grouping.data[].protectedPercentage |
Double |
Percentage of clicks that were protected |
| grouping.data[].blocked |
Long |
Number of clicks blocked |
| grouping.data[].isolated |
Long |
Number of clicks isolated |
| grouping.data[].permitted |
Long |
Number of clicks permitted |
| totals |
Object |
Aggregate totals across all periods |
| totals.totalClicks |
Long |
Total number of clicks |
| totals.protectedPercentage |
Double |
Overall percentage of clicks protected |
| totals.blocked |
Long |
Total number of clicks blocked |
| totals.isolated |
Long |
Total number of clicks isolated |
| totals.permitted |
Long |
Total number of clicks permitted |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/effectiveness-reports/clicks-protected?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /effectiveness-reports/url-rewritten-summary
Retrieves summary metrics for URLs that have been rewritten by URL Defense.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"rewrittenURLs": {
"countURLs": 15000,
"countMessages": 12000,
"reasons": [
{
"reason": "URL Defense Rewritten",
"countURLs": 10000,
"countMessages": 8000
}
]
},
"nonRewrittenURLsDueToPPS": {
"countURLs": 500,
"countMessages": 400,
"reasons": []
},
"nonRewrittenURLs": {
"countURLs": 200,
"countMessages": 150,
"reasons": []
}
}
Response Fields:
| Field |
Type |
Description |
| rewrittenURLs |
Object |
Statistics for URLs that were rewritten |
| rewrittenURLs.countURLs |
Long |
Total count of rewritten URLs |
| rewrittenURLs.countMessages |
Long |
Total count of messages containing rewritten URLs |
| rewrittenURLs.reasons |
Array |
List of reasons for URL rewriting |
| rewrittenURLs.reasons[].reason |
String |
Reason description for URL rewriting |
| rewrittenURLs.reasons[].countURLs |
Long |
Count of URLs for this reason |
| rewrittenURLs.reasons[].countMessages |
Long |
Count of messages for this reason |
| nonRewrittenURLsDueToPPS |
Object |
Statistics for URLs not rewritten due to PPS (Proofpoint Protection Server) |
| nonRewrittenURLsDueToPPS.countURLs |
Long |
Total count of non-rewritten URLs due to PPS |
| nonRewrittenURLsDueToPPS.countMessages |
Long |
Total count of messages with non-rewritten URLs due to PPS |
| nonRewrittenURLsDueToPPS.reasons |
Array |
List of reasons for non-rewriting due to PPS |
| nonRewrittenURLs |
Object |
Statistics for URLs that were not rewritten |
| nonRewrittenURLs.countURLs |
Long |
Total count of non-rewritten URLs |
| nonRewrittenURLs.countMessages |
Long |
Total count of messages with non-rewritten URLs |
| nonRewrittenURLs.reasons |
Array |
List of reasons for non-rewriting |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/effectiveness-reports/url-rewritten-summary?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /effectiveness-reports/custom-blocklist-activity
Retrieves activity metrics for custom blocklists configured in the system.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"blocklistsConfigured": true,
"activity": [
{
"classification": "MALWARE",
"urlsAdded": 50,
"urlsWithActivity": 25,
"clicksBlocked": 100,
"clicksPermitted": 5,
"clicksIsolated": 10
}
]
}
Response Fields:
| Field |
Type |
Description |
| blocklistsConfigured |
Boolean |
Whether custom blocklists are configured for the customer |
| activity |
Array |
List of blocklist activity by classification |
| activity[].classification |
ThreatClassification |
Threat classification type (MALWARE, PHISHING, SPAM, IMPOSTOR) |
| activity[].urlsAdded |
Integer |
Number of URLs added to the blocklist |
| activity[].urlsWithActivity |
Integer |
Number of URLs that had click activity |
| activity[].clicksBlocked |
Integer |
Number of clicks that were blocked |
| activity[].clicksPermitted |
Integer |
Number of clicks that were permitted |
| activity[].clicksIsolated |
Integer |
Number of clicks that were isolated |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/effectiveness-reports/custom-blocklist-activity?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
Organization Reports Endpoints
GET /organization-reports/historical-attack-index-trending
Retrieves historical attack index trend data with comparison against selected benchmarks.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| interval |
String |
Time interval for trending data |
Valid values: 1Y, MAX |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| comparison |
List<String> |
- |
List of comparison benchmarks (e.g., industry verticals, CUSTOMER_YEAR_OVER_YEAR). Maximum 4 options allowed. |
Valid vertical names or CUSTOMER_YEAR_OVER_YEAR. Note: CUSTOMER_YEAR_OVER_YEAR is only allowed when interval=1Y |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| interval |
Missing |
Missing required interval parameter. Allowed values are: [1Y, MAX]. |
| comparison |
Too many values |
Too many comparison values: {count}. Maximum allowed is 4. |
| comparison |
Empty value |
Invalid comparison parameter: empty value. |
| comparison |
Invalid value |
Invalid comparison parameter: {value}. Please use valid Vertical names or CUSTOMER_YEAR_OVER_YEAR. |
| comparison |
YoY with wrong interval |
CUSTOMER_YEAR_OVER_YEAR is only allowed when interval=1Y. |
Sample 200 Response:
{
"customer": {
"lines": [
{
"timePeriod": "MONTH",
"scores": [
{
"date": "2024-01-01",
"score": 85
}
]
}
]
},
"verticals": [
{
"name": "TECHNOLOGY",
"lines": [
{
"timePeriod": "MONTH",
"scores": [
{
"date": "2024-01-01",
"score": 75
}
]
}
]
}
]
}
Response Fields:
| Field |
Type |
Description |
| customer |
Object (optional) |
Customer trending lines data |
| customer.lines |
Array |
List of trend lines for the customer |
| customer.lines[].timePeriod |
TimePeriod |
Time period for the trend line |
| customer.lines[].scores |
Array (optional) |
List of trend line points |
| customer.lines[].scores[].date |
String |
Date for this data point |
| customer.lines[].scores[].score |
Integer |
Score value for this data point |
| verticals |
Array |
List of vertical trending lines |
| verticals[].name |
String |
Name of the vertical |
| verticals[].lines |
Array |
List of trend lines for this vertical |
| verticals[].lines[].timePeriod |
TimePeriod |
Time period for the trend line |
| verticals[].lines[].scores |
Array (optional) |
List of trend line points |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/organization-reports/historical-attack-index-trending?interval=1Y&comparison=TECHNOLOGY" -H "Authorization: Bearer YOUR_TOKEN"
GET /organization-reports/industry-comparison
Compares organization's threat metrics against selected industry verticals over a specified interval.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| startMonth |
String |
Start month in YYYY-MM format |
Must be valid YYYY-MM format within allowed range: from last 13 months to current month minus interval value (MONTH=1, QUARTER=3) |
| interval |
String |
Time interval for comparison |
Valid values: MONTH, QUARTER |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| industries |
List<String> |
Customer's default |
List of industry verticals. Maximum 3 allowed. |
Valid industry names |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| industries |
Too many values |
Too many industries specified: {count}. Maximum allowed is 3 industries. |
| industries |
Invalid value |
Invalid industries parameter: {value}. Please use valid industry names. |
| startMonth |
Invalid format/range |
Invalid query param startMonth. Please use format YYYY-MM within the allowed range : from last 13 months to current month minus interval value (MONTH=1, QUARTER=3), |
Sample 200 Response:
{
"customer": {
"attackIndex": 85,
"families": [
{
"name": "Emotet",
"score": 45,
"percentContribution": 0.5294
}
]
},
"verticals": [
{
"name": "TECHNOLOGY",
"attackIndex": 75,
"families": [
{
"name": "Trickbot",
"score": 35,
"percentContribution": 0.4667
}
]
}
]
}
Response Fields:
| Field |
Type |
Description |
| customer |
Object (optional) |
Customer's attack index data |
| customer.attackIndex |
Integer |
Customer's overall attack index score |
| customer.families |
Array |
List of threat families contributing to the attack index |
| customer.families[].name |
String |
Name of the threat family |
| customer.families[].score |
Integer |
Score for this threat family |
| customer.families[].percentContribution |
Double |
Percentage contribution of this family to the total attack index |
| verticals |
Array (optional) |
List of vertical/industry attack indices for comparison |
| verticals[].name |
String |
Name of the vertical/industry |
| verticals[].attackIndex |
Integer |
Attack index for this vertical |
| verticals[].families |
Array |
List of threat families for this vertical |
| verticals[].families[].name |
String |
Name of the threat family |
| verticals[].families[].score |
Integer |
Score for this threat family |
| verticals[].families[].percentContribution |
Double |
Percentage contribution of this family to the vertical's attack index |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/organization-reports/industry-comparison?startMonth=2024-01&interval=QUARTER&industries=TECHNOLOGY" -H "Authorization: Bearer YOUR_TOKEN"
Threat Landscape Reports Endpoints
GET /landscape-reports/threat-categories
Retrieves threat category statistics for the threat landscape reports.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"totalVolume": 5000,
"categories": [
{
"name": "Malware",
"volume": 2500,
"percentage": 0.5
},
{
"name": "Phishing",
"volume": 1500,
"percentage": 0.3
},
{
"name": "BEC",
"volume": 1000,
"percentage": 0.2
}
]
}
Response Fields:
| Field |
Type |
Description |
| totalVolume |
Integer |
Total threat volume across all categories |
| categories |
Array |
List of threat categories with metrics |
| categories[].name |
String |
Threat category name |
| categories[].volume |
Integer |
Number of threats in this category |
| categories[].percentage |
Double |
Proportion of total volume (0.0 to 1.0) |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/threat-categories?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/landscape-trend
Retrieves threat landscape trend data with configurable grouping and breakdown.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| breakdownBy |
String |
OBJECTIVES |
Breakdown dimension |
Valid values: OBJECTIVES, FAMILIES, MALWARE, ACTORS, TECHNIQUES, THEME |
| groupBy |
String |
WEEK |
Time grouping |
Valid values: DAY, WEEK, MONTH, QUARTER. Allowed values depend on date range: 0-13 days: DAY only; 14-30 days: DAY, WEEK; 31-89 days: DAY, WEEK, MONTH; 90 days: WEEK, MONTH, QUARTER |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| breakdownBy |
Invalid value |
Invalid breakdown type '{value}' requested. |
| groupBy |
Invalid value |
Invalid groupBy value: {value}. Please use one of: DAY, WEEK, MONTH |
| groupBy |
Invalid for date range (0-13 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges up to 13 days, only DAY grouping is allowed. |
| groupBy |
Invalid for date range (14-30 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 14 days and up to 30 days, allowed dateGrouping values are: DAY, WEEK. |
| groupBy |
Invalid for date range (31-89 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 30 days and up to 89 days, allowed dateGrouping values are: DAY, WEEK, MONTH. |
| groupBy |
Invalid for date range (90 days) |
Invalid groupBy '{value}' for the specified date range of 90 days. For 90 day ranges, allowed dateGrouping values are: WEEK, MONTH, QUARTER. |
Sample 200 Response:
{
"data": [
{
"date": "2024-01-01",
"breakdown": [
{
"name": "Credential Theft",
"count": 500
},
{
"name": "Malware Delivery",
"count": 300
}
]
}
]
}
Response Fields:
| Field |
Type |
Description |
| data |
Array |
List of trend data by date |
| data[].date |
String |
Date for this trend data point |
| data[].breakdown |
Array |
Breakdown of counts by name |
| data[].breakdown[].name |
String |
Name of the breakdown item (objective, family, malware, actor, technique, or theme) |
| data[].breakdown[].count |
Long |
Count for this breakdown item |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/landscape-trend?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&breakdownBy=OBJECTIVES&groupBy=WEEK" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-ten-techniques
Retrieves top 10 attack techniques for the threat landscape.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| queryType |
String |
by-volume |
Query type |
Valid values: by-volume, by-delivered, by-clicks |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| queryType |
Invalid value |
Invalid queryType parameter, allowed values: by-volume, by-delivered, by-clicks |
Sample 200 Response:
{
"type": "techniques",
"queryBy": "all-messages",
"resources": [
{
"id": null,
"name": "T1566.001 - Spearphishing Attachment",
"type": null,
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"id": null,
"name": "T1566.002 - Spearphishing Link",
"type": null,
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (techniques) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (all-messages, delivered-messages, all-clicks, at-risk-messages) |
| resources |
Array |
List of top technique details |
| resources[].id |
UUID (nullable) |
Unique identifier (null for techniques) |
| resources[].name |
String |
Name of the technique (MITRE ATT&CK format) |
| resources[].type |
String (nullable) |
Type/category (null for techniques) |
| resources[].total |
Long |
Total count for this technique |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-ten-techniques?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&queryType=by-volume" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-ten-malware
Retrieves top 10 malware threats for the threat landscape.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| queryType |
String |
by-volume |
Query type |
Valid values: by-volume, by-delivered, by-clicks |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| queryType |
Invalid value |
Invalid queryType parameter, allowed values: by-volume, by-delivered, by-clicks |
Sample 200 Response:
{
"type": "malware",
"queryBy": "all-messages",
"resources": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Emotet",
"type": "Trojan",
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "QakBot",
"type": "Banking Trojan",
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (malware) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (all-messages, delivered-messages, all-clicks, at-risk-messages) |
| resources |
Array |
List of top malware details |
| resources[].id |
UUID (nullable) |
Unique identifier for the malware |
| resources[].name |
String |
Name of the malware |
| resources[].type |
String (nullable) |
Type/category of the malware (e.g., Trojan, Ransomware) |
| resources[].total |
Long |
Total count for this malware |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-ten-malware?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&queryType=by-volume" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-ten-actors
Retrieves top 10 threat actors for the threat landscape.
Required Parameters:
| Name |
Type |
Description |
Restrictinos |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| queryType |
String |
by-volume |
Query type |
Valid values: by-volume, by-delivered, by-clicks |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| queryType |
Invalid value |
Invalid queryType parameter, allowed values: by-volume, by-delivered, by-clicks |
Sample 200 Response:
{
"type": "actors",
"queryBy": "all-messages",
"resources": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "TA505",
"type": "APT",
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "APT29",
"type": "APT",
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (actors) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (all-messages, delivered-messages, all-clicks, at-risk-messages) |
| resources |
Array |
List of top actor details |
| resources[].id |
UUID (nullable) |
Unique identifier for the actor |
| resources[].name |
String |
Name of the threat actor |
| resources[].type |
String (nullable) |
Type/category of the actor (e.g., APT, Cybercrime) |
| resources[].total |
Long |
Total count for this actor |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-ten-actors?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&queryType=by-volume" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-ten-families
Retrieves top 10 threat families for the threat landscape.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| queryType |
String |
by-volume |
Query type |
Valid values: by-volume, by-delivered, by-clicks |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| queryType |
Invalid value |
Invalid queryType parameter, allowed values: by-volume, by-delivered, by-clicks |
Sample 200 Response:
{
"type": "families",
"queryBy": "all-messages",
"resources": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Emotet Family",
"type": null,
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Trickbot Family",
"type": null,
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (families) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (all-messages, delivered-messages, all-clicks, at-risk-messages) |
| resources |
Array |
List of top family details |
| resources[].id |
UUID (nullable) |
Unique identifier for the family |
| resources[].name |
String |
Name of the threat family |
| resources[].type |
String (nullable) |
Type/category (null for families) |
| resources[].total |
Long |
Total count for this family |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-ten-families?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&queryType=by-volume" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-ten-root-domains-for-url-attacks
Retrieves top 10 root domains used in URL-based attacks.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| queryType |
String |
by-volume |
Query type |
Valid values: by-volume, by-delivered, by-clicks |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| queryType |
Invalid value |
Invalid queryType parameter, allowed values: by-volume, by-delivered, by-clicks |
Sample 200 Response:
{
"type": "top-root-domains",
"queryBy": "all-messages",
"resources": [
{
"id": null,
"name": "malicious-domain.com",
"type": null,
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"id": null,
"name": "phishing-site.net",
"type": null,
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (top-root-domains) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (all-messages, delivered-messages, all-clicks, at-risk-messages) |
| resources |
Array |
List of top root domain details |
| resources[].id |
UUID (nullable) |
Unique identifier (null for domains) |
| resources[].name |
String |
Root domain name |
| resources[].type |
String (nullable) |
Type/category (null for domains) |
| resources[].total |
Long |
Total count for this domain |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-ten-root-domains-for-url-attacks?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&queryType=by-volume" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-ten-subdomains-for-url-attacks
Retrieves top 10 subdomains used in URL-based attacks.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| queryType |
String |
by-volume |
Query type |
Valid values: by-volume, by-delivered, by-clicks |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| queryType |
Invalid value |
Invalid queryType parameter, allowed values: by-volume, by-delivered, by-clicks |
Sample 200 Response:
{
"type": "top-subdomains",
"queryBy": "all-messages",
"resources": [
{
"id": null,
"name": "login.malicious-domain.com",
"type": null,
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"id": null,
"name": "secure.phishing-site.net",
"type": null,
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (top-subdomains) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (all-messages, delivered-messages, all-clicks, at-risk-messages) |
| resources |
Array |
List of top subdomain details |
| resources[].id |
UUID (nullable) |
Unique identifier (null for subdomains) |
| resources[].name |
String |
Full subdomain name |
| resources[].type |
String (nullable) |
Type/category (null for subdomains) |
| resources[].total |
Long |
Total count for this subdomain |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-ten-subdomains-for-url-attacks?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&queryType=by-volume" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-ten-domains-sending-threats
Retrieves top 10 domains sending threat messages.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| queryType |
String |
by-volume |
Query type |
Valid values: by-volume, by-delivered, by-clicks |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| queryType |
Invalid value |
Invalid queryType parameter, allowed values: by-volume, by-delivered, by-clicks |
Sample 200 Response:
{
"type": "top-sender-domains",
"queryBy": "all-messages",
"resources": [
{
"id": null,
"name": "spam-sender.com",
"type": null,
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"id": null,
"name": "malware-distributor.net",
"type": null,
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (top-sender-domains) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (all-messages, delivered-messages, all-clicks, at-risk-messages) |
| resources |
Array |
List of top sender domain details |
| resources[].id |
UUID (nullable) |
Unique identifier (null for sender domains) |
| resources[].name |
String |
Sender domain name |
| resources[].type |
String (nullable) |
Type/category (null for sender domains) |
| resources[].total |
Long |
Total count for this sender domain |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-ten-domains-sending-threats?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&queryType=by-volume" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-ten-campaigns
Retrieves top 10 threat campaigns for the threat landscape.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| queryType |
String |
by-volume |
Query type |
Valid values: by-volume, by-delivered, by-clicks |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| queryType |
Invalid value |
Invalid queryType parameter, allowed values: by-volume, by-delivered, by-clicks |
Sample 200 Response:
{
"type": "top-campaigns",
"queryBy": "all-messages",
"resources": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Emotet Campaign Q1 2024",
"type": "Malware Distribution",
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Credential Phishing Wave",
"type": "Phishing",
"total": 3000,
"preDeliveryProtected": 2700,
"postDeliveryProtected": 250,
"potentiallyExposed": 50
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (top-campaigns) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (all-messages, delivered-messages, all-clicks, at-risk-messages) |
| resources |
Array |
List of top campaign details |
| resources[].id |
UUID (nullable) |
Unique identifier for the campaign |
| resources[].name |
String |
Name of the campaign |
| resources[].type |
String (nullable) |
Type/category of the campaign |
| resources[].total |
Long |
Total count for this campaign |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-ten-campaigns?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&queryType=by-volume" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/overview-headline
Retrieves headline statistics for the threat landscape overview.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"numberOfMessagesDelivered": 5000,
"numberOfMessagesBlocked": 15000,
"totalCampaigns": 150,
"totalIndividualThreats": 2000,
"totalAttachmentThreats": 3000,
"totalURLThreats": 5000,
"totalMessageTextThreats": 1000
}
Response Fields:
| Field |
Type |
Description |
| numberOfMessagesDelivered |
Long |
Number of messages delivered |
| numberOfMessagesBlocked |
Long |
Number of messages blocked |
| totalCampaigns |
Long |
Total number of campaigns |
| totalIndividualThreats |
Long |
Total number of individual threats |
| totalAttachmentThreats |
Long |
Total number of attachment-based threats |
| totalURLThreats |
Long |
Total number of URL-based threats |
| totalMessageTextThreats |
Long |
Total number of message text-based threats |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/overview-headline?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-threat-objectives
Retrieves top threat objectives across the specified time range.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"type": "threat-objectives",
"queryBy": "all-messages",
"resources": [
{
"id": null,
"name": "Credential Theft",
"type": null,
"total": 5000,
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (threat-objectives) |
| queryBy |
TopResourceQueryBy |
Query filter type (all-messages, delivered-messages, all-clicks) |
| resources |
Array |
List of threat objective details |
| resources[].id |
UUID (nullable) |
Unique identifier (null for objectives) |
| resources[].name |
String |
Name of the threat objective |
| resources[].type |
String (nullable) |
Type/category (null for objectives) |
| resources[].total |
Long |
Total count for this objective |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-threat-objectives?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/top-bec-themes
Retrieves top BEC themes for the threat landscape.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"type": "top-bec-themes",
"queryBy": null,
"resources": [
{
"id": null,
"name": "CEO Fraud",
"type": null,
"total": 500,
"preDeliveryProtected": 450,
"postDeliveryProtected": 40,
"potentiallyExposed": 10
},
{
"id": null,
"name": "Invoice Fraud",
"type": null,
"total": 300,
"preDeliveryProtected": 270,
"postDeliveryProtected": 25,
"potentiallyExposed": 5
}
]
}
Response Fields:
| Field |
Type |
Description |
| type |
TopResourceQueryType |
Type of resource query (top-bec-themes) |
| queryBy |
TopResourceQueryBy (nullable) |
Query filter type (null for BEC themes) |
| resources |
Array |
List of BEC theme details |
| resources[].id |
UUID (nullable) |
Unique identifier (null for BEC themes) |
| resources[].name |
String |
Name of the BEC theme (e.g., CEO Fraud, Invoice Fraud) |
| resources[].type |
String (nullable) |
Type/category (null for BEC themes) |
| resources[].total |
Long |
Total count for this theme |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/top-bec-themes?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/vertically-targeted-activity
Retrieves vertically targeted threat activity.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"totalCampaigns": 150,
"totalIndividualThreats": 2000,
"totalVerticalTargetCampaigns": 50,
"verticalTargetCampaignsPctTotal": 0.333,
"totalVerticalTargetIndividualThreats": 500,
"verticalTargetIndividualThreatsPctTotal": 0.25,
"totalIntendedUsers": 1000,
"totalMessages": 5000,
"totalClicks": 200,
"verticals": {
"TECHNOLOGY": {
"campaigns": 30,
"individualThreats": 300,
"intendedUsers": 500,
"messages": 2500,
"clicks": 100
}
}
}
Response Fields:
| Field |
Type |
Description |
| totalCampaigns |
Long |
Total number of campaigns |
| totalIndividualThreats |
Long |
Total number of individual threats |
| totalVerticalTargetCampaigns |
Long |
Total number of vertical-targeted campaigns |
| verticalTargetCampaignsPctTotal |
Double |
Percentage of vertical-targeted campaigns relative to total campaigns |
| totalVerticalTargetIndividualThreats |
Long |
Total number of vertical-targeted individual threats |
| verticalTargetIndividualThreatsPctTotal |
Double |
Percentage of vertical-targeted individual threats relative to total |
| totalIntendedUsers |
Long |
Total number of intended users |
| totalMessages |
Long |
Total number of messages |
| totalClicks |
Long |
Total number of clicks |
| verticals |
Object |
Map of vertical names to activity details |
| verticals[vertical].campaigns |
Long |
Number of campaigns for this vertical |
| verticals[vertical].individualThreats |
Long |
Number of individual threats for this vertical |
| verticals[vertical].intendedUsers |
Long |
Number of intended users for this vertical |
| verticals[vertical].messages |
Long |
Number of messages for this vertical |
| verticals[vertical].clicks |
Long |
Number of clicks for this vertical |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/vertically-targeted-activity?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/threat-types-by-message-volume
Retrieves threat types aggregated by message volume.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"messageTextMessages": 1000,
"urlMessages": 5000,
"attachmentMessages": 3000,
"hybridMessages": 500,
"totalMessages": 9500,
"messageTextPctTotal": 0.1053,
"urlPctTotal": 0.5263,
"attachmentPctTotal": 0.3158,
"hybridPctTotal": 0.0526
}
Response Fields:
| Field |
Type |
Description |
| messageTextMessages |
Long |
Number of messages with text-based threats |
| urlMessages |
Long |
Number of messages with URL-based threats |
| attachmentMessages |
Long |
Number of messages with attachment-based threats |
| hybridMessages |
Long |
Number of messages with hybrid threats (multiple types) |
| totalMessages |
Long |
Total number of messages (derived: sum of all message types) |
| messageTextPctTotal |
Double |
Percentage of text-based threat messages relative to total |
| urlPctTotal |
Double |
Percentage of URL-based threat messages relative to total |
| attachmentPctTotal |
Double |
Percentage of attachment-based threat messages relative to total |
| hybridPctTotal |
Double |
Percentage of hybrid threat messages relative to total |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/threat-types-by-message-volume?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/threat-campaigns-vs-individual-threats
Retrieves comparison of threat campaigns versus individual threats.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"totalThreats": 10000,
"totalCampaigns": 150,
"totalIndividualThreats": 2000,
"totalGroupedThreats": 8000,
"individualThreatsPctTotal": 0.2,
"groupedThreatsPctTotal": 0.8
}
Response Fields:
| Field |
Type |
Description |
| totalThreats |
Long |
Total number of threats |
| totalCampaigns |
Long |
Total number of campaigns |
| totalIndividualThreats |
Long |
Total number of individual (non-campaign) threats |
| totalGroupedThreats |
Long |
Total number of grouped (campaign) threats |
| individualThreatsPctTotal |
Double |
Percentage of individual threats relative to total |
| groupedThreatsPctTotal |
Double |
Percentage of grouped threats relative to total |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/threat-campaigns-vs-individual-threats?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /landscape-reports/spread-and-targeting
Retrieves spread and targeting metrics.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"verticals": [
"TECHNOLOGY",
"FINANCE"
],
"totalIndividualThreats": 2000,
"totalVerticalTargetThreats": 500,
"totalLimitedSpreadThreats": 300,
"totalGeographyTargetThreats": 200,
"verticalTargetThreatsPctTotal": 0.25,
"limitedSpreadThreatsPctTotal": 0.15,
"geographyTargetThreatsPctTotal": 0.1
}
Response Fields:
| Field |
Type |
Description |
| verticals |
Array |
List of vertical/industry names |
| totalIndividualThreats |
Long |
Total number of individual threats |
| totalVerticalTargetThreats |
Long |
Total number of vertical-targeted threats |
| totalLimitedSpreadThreats |
Long |
Total number of limited spread threats |
| totalGeographyTargetThreats |
Long |
Total number of geography-targeted threats |
| verticalTargetThreatsPctTotal |
Double |
Percentage of vertical-targeted threats relative to total individual threats |
| limitedSpreadThreatsPctTotal |
Double |
Percentage of limited spread threats relative to total individual threats |
| geographyTargetThreatsPctTotal |
Double |
Percentage of geography-targeted threats relative to total individual threats |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/landscape-reports/spread-and-targeting?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
People Reports Endpoints
GET /people-reports/top-ten-recipients
Retrieves top 10 users who received the most threat messages.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"users": mailto:user@example.com",
"vip": true,
"messages": 500,
"latestReceived": "2024-01-15T10:30:00Z"
},
{
"email": "mailto:user2@example.com",
"vip": false,
"messages": 350,
"latestReceived": "2024-01-14T15:45:00Z"
}
]
}
Response Fields:
| Field |
Type |
Description |
| users |
Array |
List of top recipient users |
| users[].email |
String |
Email address of the user |
| users[].vip |
Boolean |
Whether the user is marked as VIP |
| users[].messages |
Long |
Number of threat messages received |
| users[].latestReceived |
DateTime |
Timestamp of latest threat message received |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/people-reports/top-ten-recipients?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /people-reports/top-ten-clickers
Retrieves top 10 users who clicked on the most malicious URLs.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"users": mailto:user@example.com",
"vip": false,
"clicks": 25,
"latestClick": "2024-01-15T10:30:00Z"
},
{
"email": "mailto:user2@example.com",
"vip": true,
"clicks": 18,
"latestClick": "2024-01-14T09:15:00Z"
}
]
}
Response Fields:
| Field |
Type |
Description |
| users |
Array |
List of top clicker users |
| users[].email |
String |
Email address of the user |
| users[].vip |
Boolean |
Whether the user is marked as VIP |
| users[].clicks |
Long |
Number of malicious URL clicks |
| users[].latestClick |
DateTime |
Timestamp of latest click |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/people-reports/top-ten-clickers?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /people-reports/top-ten-isolated-clickers
Retrieves top 10 users who had the most clicks isolated by Browser Isolation.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"users": mailto:user@example.com",
"vip": false,
"isolatedClicks": 15,
"latestIsolatedClick": "2024-01-15T10:30:00Z"
},
{
"email": "mailto:user2@example.com",
"vip": true,
"isolatedClicks": 12,
"latestIsolatedClick": "2024-01-13T14:20:00Z"
}
]
}
Response Fields:
| Field |
Type |
Description |
| users |
Array |
List of top isolated clicker users |
| users[].email |
String |
Email address of the user |
| users[].vip |
Boolean |
Whether the user is marked as VIP |
| users[].isolatedClicks |
Long |
Number of clicks that were isolated |
| users[].latestIsolatedClick |
DateTime |
Timestamp of latest isolated click |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/people-reports/top-ten-isolated-clickers?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /people-Reports/very-attacked-people/list
Retrieves the list of Very Attacked People (VAP) with detailed information.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"veryAttackedPeopleList": [
{
"email": "john.doe@example.com",
"name": "John Doe",
"title": "CEO",
"department": "Executive",
"location": "New York",
"attackIndex": 95.5,
"families": [
{
"name": "Emotet",
"score": 0.45
},
{
"name": "Trickbot",
"score": 0.35
}
]
}
],
"totalRows": 150
}
Response Fields:
| Field |
Type |
Description |
| veryAttackedPeopleList |
Array |
List of very attacked people |
| veryAttackedPeopleList[].email |
String |
Email address of the person |
| veryAttackedPeopleList[].name |
String |
Name of the person |
| veryAttackedPeopleList[].title |
String |
Job title of the person |
| veryAttackedPeopleList[].department |
String |
Department of the person |
| veryAttackedPeopleList[].location |
String |
Location of the person |
| veryAttackedPeopleList[].attackIndex |
Double |
Attack index score for the person |
| veryAttackedPeopleList[].families |
Array (nullable) |
List of threat families targeting this person |
| veryAttackedPeopleList[].families[].name |
String |
Name of the threat family |
| veryAttackedPeopleList[].families[].score |
Double |
Score/percentage for this threat family |
| totalRows |
Long |
Total number of VAP records |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/people-reports/very-attacked-people/list?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /people-Reports/very-attacked-people/summary
Retrieves summary statistics for Very Attacked People (VAP).
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"veryAttackedPeopleSummary": {
"vapThresholdScore": 75.0,
"averagePersonScore": 25.5,
"relativeFactor": 2.94,
"vapCount": 15
}
}
Response Fields:
| Field |
Type |
Description |
| veryAttackedPeopleSummary |
Object |
VAP summary statistics |
| veryAttackedPeopleSummary.vapThresholdScore |
Float |
Threshold score to qualify as a VAP |
| veryAttackedPeopleSummary.averagePersonScore |
Float |
Average attack score across all people |
| veryAttackedPeopleSummary.relativeFactor |
Float |
Relative factor comparing VAP threshold to average |
| veryAttackedPeopleSummary.vapCount |
Integer |
Total count of very attacked people |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/people-reports/very-attacked-people/summary?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /people-Reports/vip-activity
Retrieves VIP activity and threat statistics.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"vipSummary": {
"intendedUsers": 50,
"atRiskUsers": 25,
"impactedUsers": 10,
"threats": 500,
"messages": 1200
},
"vipUsers": [
{
"email": "ceo@example.com",
"name": "John CEO",
"title": "Chief Executive Officer",
"messagesBlocked": 150,
"messagesDelivered": 50,
"clicksPermitted": 5,
"clicksBlocked": 20
}
]
}
Response Fields:
| Field |
Type |
Description |
| vipSummary |
Object |
Summary statistics for VIP users |
| vipSummary.intendedUsers |
Long |
Number of intended VIP users targeted |
| vipSummary.atRiskUsers |
Long |
Number of VIP users at risk |
| vipSummary.impactedUsers |
Long |
Number of VIP users impacted |
| vipSummary.threats |
Long |
Total number of threats targeting VIPs |
| vipSummary.messages |
Long |
Total number of messages targeting VIPs |
| vipUsers |
Array |
List of VIP user details |
| vipUsers[].email |
String |
Email address of the VIP user |
| vipUsers[].name |
String |
Name of the VIP user |
| vipUsers[].title |
String |
Job title of the VIP user |
| vipUsers[].messagesBlocked |
Long |
Number of messages blocked for this user |
| vipUsers[].messagesDelivered |
Long |
Number of messages delivered to this user |
| vipUsers[].clicksPermitted |
Long |
Number of clicks permitted for this user |
| vipUsers[].clicksBlocked |
Long |
Number of clicks blocked for this user |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/people-reports/vip-activity?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
Threat Objectives Endpoints
GET /Threat-Objectives-Reports/Industry-Comparison
Compares threat objectives against selected industry verticals.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| industries |
List<String> |
Customer's default |
List of industry verticals. Maximum 3 allowed. |
Valid industry names |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| industries |
Too many values |
Too many industries specified: {count}. Maximum allowed is 3 industries. |
| industries |
Invalid value |
Invalid industries parameter: {value}. Please use valid industry names. |
Sample 200 Response:
{
"customer": {
"name": "projecttest",
"objectives": [
{
"name": "Credential Theft",
"percentContribution": 0.0
},
{
"name": "Deploy Ransomware",
"percentContribution": 0.0
},
{
"name": "Execute Fraud",
"percentContribution": 0.0
},
{
"name": "Exfiltrate Data",
"percentContribution": 0.0
},
{
"name": "Remote Access",
"percentContribution": 0.0
}
]
},
"verticals": [
{
"name": "ACCOUNTING",
"objectives": [
{
"name": "Credential Theft",
"percentContribution": 0.38910702236759287
},
{
"name": "Deploy Ransomware",
"percentContribution": 0.2012943877897945
},
{
"name": "Execute Fraud",
"percentContribution": 0.18115588271702876
},
{
"name": "Exfiltrate Data",
"percentContribution": 0.03131707095944054
},
{
"name": "Remote Access",
"percentContribution": 0.19712563616614331
}
]
}
]
}
Response Fields:
| Field |
Type |
Description |
| customerObjectives |
Array |
List of customer's threat objectives |
| customerObjectives[].name |
String |
Name of the threat objective |
| customerObjectives[].total |
Long |
Total count for this objective |
| customerObjectives[].percentContribution |
Double |
Percentage contribution of this objective |
| verticalObjectives |
Array |
List of vertical/industry threat objectives |
| verticalObjectives[].vertical |
String |
Name of the vertical/industry |
| verticalObjectives[].objectives |
Array |
List of objectives for this vertical |
| verticalObjectives[].objectives[].name |
String |
Name of the threat objective |
| verticalObjectives[].objectives[].total |
Long |
Total count for this objective |
| verticalObjectives[].objectives[].percentContribution |
Double |
Percentage contribution of this objective |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/threat-objectives-reports/industry-comparison?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&industries=TECHNOLOGY" -H "Authorization: Bearer YOUR_TOKEN"
GET /Threat-Objectives-Reports/Messages-Protected
Retrieves messages protected statistics grouped by threat objectives.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"resources": [
{
"name": "Credential Theft",
"preDeliveryProtected": 4500,
"postDeliveryProtected": 400,
"potentiallyExposed": 100,
"total": 5000
}
],
"comparisonResources": [
{
"name": "Credential Theft",
"preDeliveryProtected": 4000,
"postDeliveryProtected": 400,
"potentiallyExposed": 100,
"total": 4500
}
],
"lastUpdatedUntil": "2024-01-31T23:59:59Z"
}
Response Fields:
| Field |
Type |
Description |
| resources |
Array |
List of threat objective details for current period |
| resources[].name |
String |
Name of the threat objective |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
| resources[].total |
Long |
Total count for this objective |
| comparisonResources |
Array |
List of threat objective details for comparison period |
| comparisonResources[].name |
String |
Name of the threat objective |
| comparisonResources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| comparisonResources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| comparisonResources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
| comparisonResources[].total |
Long |
Total count for this objective |
| lastUpdatedUntil |
DateTime (nullable) |
Timestamp of last data update |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/threat-objectives-reports/messages-protected?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /Threat-Objectives-Reports/Threat-Objectives-Trend
Retrieves threat objectives trend data over time.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| groupBy |
String |
WEEK |
Time grouping |
Valid values: DAY, WEEK, MONTH, QUARTER. Allowed values depend on date range: 0-13 days: DAY only; 14-30 days: DAY, WEEK; 31-89 days: DAY, WEEK, MONTH; 90 days: WEEK, MONTH, QUARTER |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| groupBy |
Invalid value |
Invalid groupBy value: {value}. Please use one of: DAY, WEEK, MONTH |
| groupBy |
Invalid for date range (0-13 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges up to 13 days, only DAY grouping is allowed. |
| groupBy |
Invalid for date range (14-30 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 14 days and up to 30 days, allowed dateGrouping values are: DAY, WEEK. |
| groupBy |
Invalid for date range (31-89 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 30 days and up to 89 days, allowed dateGrouping values are: DAY, WEEK, MONTH. |
| groupBy |
Invalid for date range (90 days) |
Invalid groupBy '{value}' for the specified date range of 90 days. For 90 day ranges, allowed dateGrouping values are: WEEK, MONTH, QUARTER. |
Sample 200 Response:
{
"data": [
{
"date": "2026-01-19T00:00:00.000Z",
"breakdown": [
{
"name": "Credential Theft",
"count": 0
},
{
"name": "Deploy Ransomware",
"count": 0
},
{
"name": "Exfiltrate Data",
"count": 0
},
{
"name": "Remote Access",
"count": 0
}
]
}
]
}
Response Fields:
| Field |
Type |
Description |
| data |
Array |
List of trend data by date |
| data[].date |
String |
Date for this trend data point |
| data[].breakdown |
Array |
Breakdown of counts by name |
| data[].breakdown[].name |
String |
Name of the breakdown item (objective, family, malware, actor, technique, or theme) |
| data[].breakdown[].count |
Long |
Count for this breakdown item |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/threat-objectives-reports/threat-objectives-trend?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&groupBy=WEEK" -H "Authorization: Bearer YOUR_TOKEN"
BEC Reports Endpoints
GET /Bec-Reports/Top-Bec-Themes
Retrieves top BEC themes for the specified time range.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"resources": [
{
"name": "Testing@",
"preDeliveryProtected": 2,
"postDeliveryProtected": 191,
"potentiallyExposed": 1384,
"total": 1577
}
]
}
Response Fields:
| Field |
Type |
Description |
| resources |
Array |
List of BEC theme details |
| resources[].name |
String |
Name of the BEC theme (e.g., CEO Fraud, Invoice Fraud) |
| resources[].preDeliveryProtected |
Long |
Count of pre-delivery protected messages |
| resources[].postDeliveryProtected |
Long |
Count of post-delivery protected messages |
| resources[].potentiallyExposed |
Long |
Count of potentially exposed messages |
| resources[].total |
Long |
Total count for this theme |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/bec-reports/top-bec-themes?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /Bec-Reports/Bec-Themes-Trend
Retrieves BEC themes trend data over time.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| groupBy |
String |
DAY |
Time grouping |
Valid values: DAY, WEEK, MONTH. Allowed values depend on date range: 0-13 days: DAY only; 14-30 days: DAY, WEEK; 31-89 days: DAY, WEEK, MONTH; 90 days: WEEK, MONTH, QUARTER |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| groupBy |
Invalid value |
Invalid groupBy value: {value}. Please use one of: DAY, WEEK, MONTH |
| groupBy |
Invalid for date range (0-13 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges up to 13 days, only DAY grouping is allowed. |
| groupBy |
Invalid for date range (14-30 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 14 days and up to 30 days, allowed dateGrouping values are: DAY, WEEK. |
| groupBy |
Invalid for date range (31-89 days) |
Invalid groupBy '{value}' for the specified date range of {days} days. For date ranges greater than 30 days and up to 89 days, allowed dateGrouping values are: DAY, WEEK, MONTH. |
| groupBy |
Invalid for date range (90 days) |
Invalid groupBy '{value}' for the specified date range of 90 days. For 90 day ranges, allowed dateGrouping values are: WEEK, MONTH, QUARTER. |
Sample 200 Response:
{
"data": [
{
"date": "2024-01-01",
"breakdown": [
{
"name": "Lure/Task",
"count": 100
},
{
"name": "Invoicing",
"count": 75
}
]
}
]
}
Response Fields:
| Field |
Type |
Description |
| data |
Array |
List of trend data by date |
| data[].date |
String |
Date for this trend data point |
| data[].breakdown |
Array |
Breakdown of counts by BEC theme |
| data[].breakdown[].name |
String |
Name of the BEC theme |
| data[].breakdown[].count |
Long |
Count for this BEC theme |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/bec-reports/bec-themes-trend?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&groupBy=WEEK" -H "Authorization: Bearer YOUR_TOKEN"
GET /Bec-Reports/Vips-Targeted-By-Bec-Threats
Retrieves VIPs targeted by BEC threats.
Required Parameters:
| Name |
Type |
Description |
Resstrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"users": [
{
"person": "John CEO",
"title": "Chief Executive Officer",
"department": "Executive",
"vip": true,
"ato": false,
"riskExposure": "HIGH",
"isShadowAdmin": false,
"isPrivileged": true,
"attackIndex": 95.5,
"maxThreatSeverity": 10,
"becEmailThreats": 25,
"becMessagesOnEmailThreats": 50,
"suspiciousLoginsFromCloud": 2,
"attackPathsCount": 3
}
]
}
Response Fields:
| Field |
Type |
Description |
| users |
Array |
List of VIP users targeted by BEC threats |
| users[].person |
String |
Name of the person |
| users[].title |
String |
Job title |
| users[].department |
String |
Department |
| users[].vip |
Boolean |
Whether the user is a VIP |
| users[].ato |
Boolean |
Whether the user has account takeover risk |
| users[].riskExposure |
String |
Risk exposure level (HIGH, MEDIUM, LOW) |
| users[].isShadowAdmin |
Boolean |
Whether the user is a shadow admin |
| users[].isPrivileged |
Boolean |
Whether the user has privileged access |
| users[].attackIndex |
Float |
Attack index score |
| users[].maxThreatSeverity |
Integer |
Maximum threat severity score |
| users[].becEmailThreats |
Integer |
Number of BEC email threats |
| users[].becMessagesOnEmailThreats |
Integer |
Number of BEC messages on email threats |
| users[].suspiciousLoginsFromCloud |
Integer |
Number of suspicious logins from cloud |
| users[].attackPathsCount |
Integer |
Number of attack paths |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/bec-reports/vips-targeted-by-bec-threats?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /Bec-Reports/People-Targeted-By-Bec-Threats
Retrieves all people targeted by BEC threats.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"users": [
{
"person": "Jane Finance",
"title": "Finance Manager",
"department": "Finance",
"vip": false,
"ato": false,
"riskExposure": "MEDIUM",
"isShadowAdmin": false,
"isPrivileged": false,
"attackIndex": 65.5,
"maxThreatSeverity": 7,
"becEmailThreats": 15,
"becMessagesOnEmailThreats": 30,
"suspiciousLoginsFromCloud": 0,
"attackPathsCount": 1
}
]
}
Response Fields:
| Field |
Type |
Descriptioni |
| users |
Array |
List of people targeted by BEC threats |
| users[].person |
String |
Name of the person |
| users[].title |
String |
Job title |
| users[].department |
String |
Department |
| users[].vip |
Boolean |
Whether the user is a VIP |
| users[].ato |
Boolean |
Whether the user has account takeover risk |
| users[].riskExposure |
String |
Risk exposure level (HIGH, MEDIUM, LOW) |
| users[].isShadowAdmin |
Boolean |
Whether the user is a shadow admin |
| users[].isPrivileged |
Boolean |
Whether the user has privileged access |
| users[].attackIndex |
Float |
Attack index score |
| users[].maxThreatSeverity |
Integer |
Maximum threat severity score |
| users[].becEmailThreats |
Integer |
Number of BEC email threats |
| users[].becMessagesOnEmailThreats |
Integer |
Number of BEC messages on email threats |
| users[].suspiciousLoginsFromCloud |
Integer |
Number of suspicious logins from cloud |
| users[].attackPathsCount |
Integer |
Number of attack paths |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/bec-reports/people-targeted-by-bec-threats?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /Bec-Reports/Messages-Protected
Retrieves BEC messages protected statistics.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
Sample 200 Response:
{
"statsByBreakdownValue": [
{
"breakdownName": "bec",
"preDeliveryProtectedMessages": 5000,
"postDeliveryProtectedMessages": 1200,
"potentiallyExposedMessages": 300,
"breakdownProtectedMessagesTotal": 6200,
"breakdownMessagesTotal": 6500,
"breakdownMessagesProtectionPct": 0.954
}
],
"totals": {
"preDeliveryProtectedMessages": 5000,
"postDeliveryProtectedMessages": 1200,
"potentiallyExposedMessages": 300,
"overallMessagesProtectionPctTotal": 0.954
}
}
Response Fields:
| Field |
Type |
Description |
| statsByBreakdownValue |
Array |
Statistics broken down by BEC category |
| statsByBreakdownValue[].breakdownName |
String |
The breakdown name (bec) |
| statsByBreakdownValue[].preDeliveryProtectedMessages |
Long |
Number of messages protected before delivery |
| statsByBreakdownValue[].postDeliveryProtectedMessages |
Long |
Number of messages protected after delivery |
| statsByBreakdownValue[].potentiallyExposedMessages |
Long |
Number of messages potentially exposed |
| statsByBreakdownValue[].breakdownProtectedMessagesTotal |
Long |
Total protected messages for this breakdown |
| statsByBreakdownValue[].breakdownMessagesTotal |
Long |
Total messages for this breakdown |
| statsByBreakdownValue[].breakdownMessagesProtectionPct |
Double |
Percentage of messages protected |
| totals |
Object |
Overall totals |
| totals.preDeliveryProtectedMessages |
Long |
Total messages protected before delivery |
| totals.postDeliveryProtectedMessages |
Long |
Total messages protected after delivery |
| totals.potentiallyExposedMessages |
Long |
Total messages potentially exposed |
| totals.overallMessagesProtectionPctTotal |
Double |
Overall percentage of messages protected |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/bec-reports/messages-protected?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z" -H "Authorization: Bearer YOUR_TOKEN"
GET /Bec-Reports/Bec-Messages-Protected-Trend
Retrieves BEC messages protected trend data over time.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| groupBy |
String |
DAY |
Time grouping |
DAY, WEEK, MONTH, QUARTER |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| groupBy |
Invalid for date range |
Invalid groupBy '{value}' for the specified date range of {days} days. |
Sample 200 Response:
{
"breakdownName": "by-threat-category",
"groupByName": "BEC",
"messagesProtectedByDay": {
"2025-09-22T00:00:00Z": {
"maliciousMessages": 1,
"totalProtectedPercent": 1.0,
"preDeliveryProtectedMessages": 1,
"postDeliveryProtectedMessages": 0,
"postDeliveryTRQuarantinesUnRead": 0,
"postDeliveryURLRewrittenNoPermittedClicks": 0,
"potentiallyExposedMessages": 0,
"potentiallyExposedWithAttachments": 0,
"potentiallyExposedWithTextThreats": 0,
"potentiallyExposedWithPermittedClicks": 0,
"potentiallyExposedWithNonRewrittenURLs": 0
}
},
"total": {
"maliciousMessages": 1,
"totalProtectedPercent": 1.0,
"preDeliveryProtectedMessages": 1,
"postDeliveryProtectedMessages": 0,
"postDeliveryTRQuarantinesUnRead": 0,
"postDeliveryURLRewrittenNoPermittedClicks": 0,
"potentiallyExposedMessages": 0,
"potentiallyExposedWithAttachments": 0,
"potentiallyExposedWithTextThreats": 0,
"potentiallyExposedWithPermittedClicks": 0,
"potentiallyExposedWithNonRewrittenURLs": 0
}
}
Response Field Descriptions
| Field |
Type |
Description |
| breakdownName |
string |
Breakdown type name (by-threat-category) |
| groupByName |
string |
Group by name (BEC) |
| messagesProtectedByDay |
object |
Map of date-keyed statistics |
| messagesProtectedByDay[date] |
object |
Statistics for a specific date/period |
| messagesProtectedByDay[date].maliciousMessages |
long |
Number of malicious messages |
| messagesProtectedByDay[date].totalProtectedPercent |
double |
Percentage of messages protected |
| messagesProtectedByDay[date].preDeliveryProtectedMessages |
long |
Messages protected before delivery |
| messagesProtectedByDay[date].postDeliveryProtectedMessages |
long |
Messages protected after delivery |
| messagesProtectedByDay[date].postDeliveryTRQuarantinesUnRead |
long |
Post-delivery TR quarantines unread |
| messagesProtectedByDay[date].postDeliveryURLRewrittenNoPermittedClicks |
long |
Post-delivery URL rewritten with no permitted clicks |
| messagesProtectedByDay[date].potentiallyExposedMessages |
long |
Potentially exposed messages |
| messagesProtectedByDay[date].potentiallyExposedWithAttachments |
long |
Potentially exposed with attachments |
| messagesProtectedByDay[date].potentiallyExposedWithTextThreats |
long |
Potentially exposed with text threats |
| messagesProtectedByDay[date].potentiallyExposedWithPermittedClicks |
long |
Potentially exposed with permitted clicks |
| messagesProtectedByDay[date].potentiallyExposedWithNonRewrittenURLs |
long |
Potentially exposed with non-rewritten URLs |
| total |
object |
Aggregated total statistics (same fields as messagesProtectedByDay[date]) |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/bec-reports/bec-messages-protected-trend?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&groupBy=WEEK" -H "Authorization: Bearer YOUR_TOKEN"
Actor Reports Endpoints
GET /Actor-Reports/Actors
Retrieves a paginated and sorted list of top threat actors for the specified time range.
Required Parameters:
| Name |
Type |
Description |
Restrictions |
| start |
String |
Start time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
| end |
String |
End time for the reporting period in ISO 8601 UTC format |
Must be valid ISO 8601 format in UTC |
Optional Parameters:
| Name |
Type |
Default |
Description |
Restrictions |
| page |
int |
0 |
Page number for pagination |
Non-negative integer |
| size |
int |
10 |
Number of results per page |
Positive integer |
| sortBy |
String |
ATTACK_INDEX |
Field to sort by |
Valid values: ATTACK_INDEX, DISTINCT_THREATS |
| sortOrder |
String |
DESC |
Sort order |
Valid values: ASC, DESC |
Validations and Error Messages:
| Field |
Validation |
Error Message |
| start |
Invalid format |
Invalid start query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| end |
Invalid format |
Invalid end query param: {value}. Please use ISO-8601 format in UTC (e.g. 2023-01-01T00:00:00Z) |
| start/end |
Dates out of order |
The start query param {start} occurs after end query param {end}. Please ensure start is before end. |
| start/end |
Range exceeds 90 days |
The end query param {end} occurs more than 90 days after the start query param {start}. Please reduce requested time range. |
| sortBy |
Invalid value |
Invalid sortBy parameter: {value}. Allowed values: ATTACK_INDEX, DISTINCT_THREATS |
| sortOrder |
Invalid value |
Invalid sortOrder parameter: {value}. Allowed values: ASC, DESC |
Sample 200 Response:
{
"actors": [
{
"name": "JkBDZuHdkpVIcYiIHCNfGlnyQ",
"category": {
"isHighlighted": false
},
"objectives": [],
"intendedUsers": {
"allUsers": 10,
"vipUsers": 0,
"usersWithClicks": 4,
"usersWithPermittedClicks": 4,
"usersWithAccessibleThreats": 4
},
"attackIndex": 13522,
"actorMessages": {
"volume": 24,
"breakdownByDisposition": {
"preDeliveryProtectedMessages": 2,
"postDeliveryProtectedMessages": 9,
"potentiallyExposedMessages": 13
},
"twelveMonthTrend": [
{
"date": "2025-04-01",
"total": 0
},
{
"date": "2025-05-01",
"total": 0
},
{
"date": "2025-06-01",
"total": 0
},
{
"date": "2025-07-01",
"total": 0
},
{
"date": "2025-08-01",
"total": 0
},
{
"date": "2025-09-01",
"total": 0
},
{
"date": "2025-10-01",
"total": 0
},
{
"date": "2025-11-01",
"total": 0
},
{
"date": "2025-12-01",
"total": 0
},
{
"date": "2026-01-01",
"total": 0
},
{
"date": "2026-02-01",
"total": 33
},
{
"date": "2026-03-01",
"total": 0
}
]
}
}
],
"totalRows": 50
}
Response Fields:
| Field |
Type |
Description |
| actors |
Array |
List of actor widget data |
| actors[].name |
String |
Name of the threat actor |
| actors[].category |
Object |
Category information for the actor |
| actors[].category.name |
String (nullable) |
Category name |
| actors[].category.isHighlighted |
Boolean |
Whether the category is highlighted |
| actors[].objectives |
Array |
List of objectives for this actor |
| actors[].objectives[].name |
String |
Name of the objective |
| actors[].objectives[].isHighlighted |
Boolean |
Whether the objective is highlighted |
| actors[].intendedUsers |
Object |
User statistics for this actor |
| actors[].intendedUsers.allUsers |
Long |
Total number of intended users |
| actors[].intendedUsers.vipUsers |
Long |
Number of VIP users targeted |
| actors[].intendedUsers.usersWithClicks |
Long |
Number of users who clicked |
| actors[].intendedUsers.usersWithPermittedClicks |
Long |
Number of users with permitted clicks |
| actors[].intendedUsers.usersWithAccessibleThreats |
Long |
Number of users with accessible threats |
| actors[].attackIndex |
Long |
Attack index score for this actor |
| actors[].actorMessages |
Object |
Message statistics for this actor |
| actors[].actorMessages.volume |
Long |
Total message volume |
| actors[].actorMessages.breakdownByDisposition |
Object |
Message breakdown by disposition |
| actors[].actorMessages.breakdownByDisposition.preDeliveryProtectedMessages |
Long |
Pre-delivery protected messages |
| actors[].actorMessages.breakdownByDisposition.postDeliveryProtectedMessages |
Long |
Post-delivery protected messages |
| actors[].actorMessages.breakdownByDisposition.potentiallyExposedMessages |
Long |
Potentially exposed messages |
| actors[].actorMessages.twelveMonthTrend |
Array |
12-month trend data |
| actors[].actorMessages.twelveMonthTrend[].date |
String |
Date for this trend point |
| actors[].actorMessages.twelveMonthTrend[].total |
Long |
Total for this trend point |
| totalRows |
Long |
Total number of actor rows |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/actor-reports/actors?start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&page=0&size=10&sortBy=ATTACK_INDEX&sortOrder=DESC" -H "Authorization: Bearer YOUR_TOKEN"
Industries List
GET /industries
Retrieves a list of available industries/verticals for use in filtering and comparison operations.
Required Parameters:
None
Optional Parameters:
None
Validations and Error Messages:
NA
Sample 200 Response:
[
{
"key": "ACCOUNTING",
"displayName": "Accounting"
},
{
"key": "AEROSPACE",
"displayName": "Aerospace"
},
{
"key": "AGRICULTURE",
"displayName": "Agriculture"
},
{
"key": "ARTS_RECREATION",
"displayName": "Arts/Recreation"
},
{
"key": "AUTOMOTIVE",
"displayName": "Automotive"
},
{
"key": "BANKING_LENDING",
"displayName": "FinServ - Banking - Lending"
}
]
Response Fields:
| Field |
Type |
Description |
| key |
String |
Unique identifier for the industry (uppercase format). To be used in industry-comparison APIs. |
| displayName |
String |
Display name of the industry |
Example:
curl -X GET "https://threatprotection-api.proofpoint.com/api/v1/dash/reports/industries" \
-H "Authorization: Bearer YOUR_TOKEN"
