curl --location 'https://your-cloud-id.threataware.com/public-api/v1/vitals' \
--header 'Accept: application/json' \
--header 'X-ThreatAware-ApiKey: your-api-key-here'
import requests
API_KEY = "your-api-key-here"
CLOUD_ID = "sandbox"
BASE_URL = f"https://{CLOUD_ID}.threataware.com/public-api/v1"
headers = {
"Accept": "application/json",
"X-ThreatAware-ApiKey": API_KEY
}
response = requests.get(f"{BASE_URL}/vitals", headers=headers)
vitals = response.json()
print(f"Retrieved health data for {len(vitals['data'])} integrations")
# Example: Calculate overall health percentages
for integration in vitals['data']:
if integration.get('vitalsEnabled'):
deployed = integration['agentDeployedCompliant']
possible = integration['agentDeployedPossibleCompliant']
if possible > 0:
health_pct = (deployed / possible) * 100
print(f"{integration['name']}: {health_pct:.1f}% deployed")
const axios = require('axios');
const API_KEY = 'your-api-key-here';
const CLOUD_ID = 'sandbox';
const BASE_URL = `https://${CLOUD_ID}.threataware.com/public-api/v1`;
axios.get(`${BASE_URL}/vitals`, {
headers: {
'Accept': 'application/json',
'X-ThreatAware-ApiKey': API_KEY
}
})
.then(response => {
console.log(`Retrieved health data for ${response.data.data.length} integrations`);
// Example: Find integrations with Vitals enabled
const vitalsEnabled = response.data.data.filter(v => v.vitalsEnabled);
console.log(`${vitalsEnabled.length} integrations have Vitals monitoring enabled`);
});
$ApiKey = "your-api-key-here"
$CloudId = "sandbox"
$BaseUrl = "https://$CloudId.threataware.com/public-api/v1"
$Headers = @{
"Accept" = "application/json"
"X-ThreatAware-ApiKey" = $ApiKey
}
$Response = Invoke-RestMethod -Uri "$BaseUrl/vitals" -Headers $Headers -Method Get
Write-Host "Retrieved health data for $($Response.data.Count) integrations"
# Example: Show health summary for Vitals-enabled integrations
$Response.data | Where-Object { $_.vitalsEnabled } | ForEach-Object {
$deployedPct = ($_.agentDeployedCompliant / $_.agentDeployedPossibleCompliant) * 100
Write-Host "$($_.name): $([math]::Round($deployedPct, 1))% deployed"
}
{
"offset": 0,
"limit": 8,
"total": 8,
"data": [
{
"key": "mecmsystem",
"name": "SCCM",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "teamviewer",
"name": "Teamviewer",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "devices_ad",
"name": "Azure AD",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "msdefenderatp",
"name": "Microsoft Defender ATP",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 865,
"agentDeployedCompliant": 809,
"agentFunctioningPossibleCompliant": 809,
"agentFunctioningCompliant": 763,
"configurationPossibleCompliant": 763,
"configurationCompliant": 596
},
{
"key": "servicenow",
"name": "ServiceNow",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "jamf",
"name": "Jamf",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 113,
"agentDeployedCompliant": 82,
"agentFunctioningPossibleCompliant": 82,
"agentFunctioningCompliant": 80,
"configurationPossibleCompliant": 80,
"configurationCompliant": 61
},
{
"key": "crowdstrike",
"name": "Crowdstrike",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 925,
"agentDeployedCompliant": 872,
"agentFunctioningPossibleCompliant": 872,
"agentFunctioningCompliant": 834,
"configurationPossibleCompliant": 834,
"configurationCompliant": 745
},
{
"key": "devices_msgraph",
"name": "Microsoft InTune",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 865,
"agentDeployedCompliant": 764,
"agentFunctioningPossibleCompliant": 764,
"agentFunctioningCompliant": 724,
"configurationPossibleCompliant": 724,
"configurationCompliant": 551
}
],
"success": true,
"statusCode": 200,
"message": "Successfully retrieved vitals data."
}
Core Endpoints
Get Vitals
Retrieve security control health status across all integrations
GET
/
public-api
/
v1
/
vitals
curl --location 'https://your-cloud-id.threataware.com/public-api/v1/vitals' \
--header 'Accept: application/json' \
--header 'X-ThreatAware-ApiKey: your-api-key-here'
import requests
API_KEY = "your-api-key-here"
CLOUD_ID = "sandbox"
BASE_URL = f"https://{CLOUD_ID}.threataware.com/public-api/v1"
headers = {
"Accept": "application/json",
"X-ThreatAware-ApiKey": API_KEY
}
response = requests.get(f"{BASE_URL}/vitals", headers=headers)
vitals = response.json()
print(f"Retrieved health data for {len(vitals['data'])} integrations")
# Example: Calculate overall health percentages
for integration in vitals['data']:
if integration.get('vitalsEnabled'):
deployed = integration['agentDeployedCompliant']
possible = integration['agentDeployedPossibleCompliant']
if possible > 0:
health_pct = (deployed / possible) * 100
print(f"{integration['name']}: {health_pct:.1f}% deployed")
const axios = require('axios');
const API_KEY = 'your-api-key-here';
const CLOUD_ID = 'sandbox';
const BASE_URL = `https://${CLOUD_ID}.threataware.com/public-api/v1`;
axios.get(`${BASE_URL}/vitals`, {
headers: {
'Accept': 'application/json',
'X-ThreatAware-ApiKey': API_KEY
}
})
.then(response => {
console.log(`Retrieved health data for ${response.data.data.length} integrations`);
// Example: Find integrations with Vitals enabled
const vitalsEnabled = response.data.data.filter(v => v.vitalsEnabled);
console.log(`${vitalsEnabled.length} integrations have Vitals monitoring enabled`);
});
$ApiKey = "your-api-key-here"
$CloudId = "sandbox"
$BaseUrl = "https://$CloudId.threataware.com/public-api/v1"
$Headers = @{
"Accept" = "application/json"
"X-ThreatAware-ApiKey" = $ApiKey
}
$Response = Invoke-RestMethod -Uri "$BaseUrl/vitals" -Headers $Headers -Method Get
Write-Host "Retrieved health data for $($Response.data.Count) integrations"
# Example: Show health summary for Vitals-enabled integrations
$Response.data | Where-Object { $_.vitalsEnabled } | ForEach-Object {
$deployedPct = ($_.agentDeployedCompliant / $_.agentDeployedPossibleCompliant) * 100
Write-Host "$($_.name): $([math]::Round($deployedPct, 1))% deployed"
}
{
"offset": 0,
"limit": 8,
"total": 8,
"data": [
{
"key": "mecmsystem",
"name": "SCCM",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "teamviewer",
"name": "Teamviewer",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "devices_ad",
"name": "Azure AD",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "msdefenderatp",
"name": "Microsoft Defender ATP",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 865,
"agentDeployedCompliant": 809,
"agentFunctioningPossibleCompliant": 809,
"agentFunctioningCompliant": 763,
"configurationPossibleCompliant": 763,
"configurationCompliant": 596
},
{
"key": "servicenow",
"name": "ServiceNow",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "jamf",
"name": "Jamf",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 113,
"agentDeployedCompliant": 82,
"agentFunctioningPossibleCompliant": 82,
"agentFunctioningCompliant": 80,
"configurationPossibleCompliant": 80,
"configurationCompliant": 61
},
{
"key": "crowdstrike",
"name": "Crowdstrike",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 925,
"agentDeployedCompliant": 872,
"agentFunctioningPossibleCompliant": 872,
"agentFunctioningCompliant": 834,
"configurationPossibleCompliant": 834,
"configurationCompliant": 745
},
{
"key": "devices_msgraph",
"name": "Microsoft InTune",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 865,
"agentDeployedCompliant": 764,
"agentFunctioningPossibleCompliant": 764,
"agentFunctioningCompliant": 724,
"configurationPossibleCompliant": 724,
"configurationCompliant": 551
}
],
"success": true,
"statusCode": 200,
"message": "Successfully retrieved vitals data."
}
Overview
The Vitals endpoint provides access to security control health data, showing deployment, functionality, and configuration status for all Vitals-enabled integrations.This endpoint returns aggregate health data at the integration level. For device-specific Vitals status, use the
/devices endpoint which includes security tool details per device.Parameters
number
default:"0"
Set the start position of the data returned by the API
number
default:"0"
Limit each request by the provided number. Leave blank or as 0 to return all data available
string
Filter the data down to a specific tag. Blank by default, will return all data.
string
Retrieve archived historical data. Format:
yyyyMMdd (e.g., 20240819 for August 19, 2024)Use this parameter to track Vitals health over time for trend analysis and reporting.
Authentication
string
required
Your ThreatAware API key
string
default:"application/json"
Response format
Response
number
The starting position of this result set
number
The number of results returned
number
Total number of integrations
boolean
Whether the request was successful
number
HTTP status code
string
Status message
array
Show Vitals Object
Show Vitals Object
string
Integration key (e.g.,
crowdstrike, jamf, msdefenderatp)string
Human-readable integration name
boolean
Whether Vitals monitoring is enabled for this integration
number
Total number of devices with this integration (when Vitals not enabled)
vitalsEnabled is true:number
Number of devices that should have this control deployed (based on tags)
number
Number of devices where the agent is successfully deployed
number
Number of devices with agent deployed (input to Function check)
number
Number of devices where the agent is functioning correctly
number
Number of devices with functioning agent (input to Configuration check)
number
Number of devices where the agent is correctly configured
curl --location 'https://your-cloud-id.threataware.com/public-api/v1/vitals' \
--header 'Accept: application/json' \
--header 'X-ThreatAware-ApiKey: your-api-key-here'
import requests
API_KEY = "your-api-key-here"
CLOUD_ID = "sandbox"
BASE_URL = f"https://{CLOUD_ID}.threataware.com/public-api/v1"
headers = {
"Accept": "application/json",
"X-ThreatAware-ApiKey": API_KEY
}
response = requests.get(f"{BASE_URL}/vitals", headers=headers)
vitals = response.json()
print(f"Retrieved health data for {len(vitals['data'])} integrations")
# Example: Calculate overall health percentages
for integration in vitals['data']:
if integration.get('vitalsEnabled'):
deployed = integration['agentDeployedCompliant']
possible = integration['agentDeployedPossibleCompliant']
if possible > 0:
health_pct = (deployed / possible) * 100
print(f"{integration['name']}: {health_pct:.1f}% deployed")
const axios = require('axios');
const API_KEY = 'your-api-key-here';
const CLOUD_ID = 'sandbox';
const BASE_URL = `https://${CLOUD_ID}.threataware.com/public-api/v1`;
axios.get(`${BASE_URL}/vitals`, {
headers: {
'Accept': 'application/json',
'X-ThreatAware-ApiKey': API_KEY
}
})
.then(response => {
console.log(`Retrieved health data for ${response.data.data.length} integrations`);
// Example: Find integrations with Vitals enabled
const vitalsEnabled = response.data.data.filter(v => v.vitalsEnabled);
console.log(`${vitalsEnabled.length} integrations have Vitals monitoring enabled`);
});
$ApiKey = "your-api-key-here"
$CloudId = "sandbox"
$BaseUrl = "https://$CloudId.threataware.com/public-api/v1"
$Headers = @{
"Accept" = "application/json"
"X-ThreatAware-ApiKey" = $ApiKey
}
$Response = Invoke-RestMethod -Uri "$BaseUrl/vitals" -Headers $Headers -Method Get
Write-Host "Retrieved health data for $($Response.data.Count) integrations"
# Example: Show health summary for Vitals-enabled integrations
$Response.data | Where-Object { $_.vitalsEnabled } | ForEach-Object {
$deployedPct = ($_.agentDeployedCompliant / $_.agentDeployedPossibleCompliant) * 100
Write-Host "$($_.name): $([math]::Round($deployedPct, 1))% deployed"
}
{
"offset": 0,
"limit": 8,
"total": 8,
"data": [
{
"key": "mecmsystem",
"name": "SCCM",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "teamviewer",
"name": "Teamviewer",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "devices_ad",
"name": "Azure AD",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "msdefenderatp",
"name": "Microsoft Defender ATP",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 865,
"agentDeployedCompliant": 809,
"agentFunctioningPossibleCompliant": 809,
"agentFunctioningCompliant": 763,
"configurationPossibleCompliant": 763,
"configurationCompliant": 596
},
{
"key": "servicenow",
"name": "ServiceNow",
"vitalsEnabled": false,
"activeAgents": 1230
},
{
"key": "jamf",
"name": "Jamf",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 113,
"agentDeployedCompliant": 82,
"agentFunctioningPossibleCompliant": 82,
"agentFunctioningCompliant": 80,
"configurationPossibleCompliant": 80,
"configurationCompliant": 61
},
{
"key": "crowdstrike",
"name": "Crowdstrike",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 925,
"agentDeployedCompliant": 872,
"agentFunctioningPossibleCompliant": 872,
"agentFunctioningCompliant": 834,
"configurationPossibleCompliant": 834,
"configurationCompliant": 745
},
{
"key": "devices_msgraph",
"name": "Microsoft InTune",
"vitalsEnabled": true,
"agentDeployedPossibleCompliant": 865,
"agentDeployedCompliant": 764,
"agentFunctioningPossibleCompliant": 764,
"agentFunctioningCompliant": 724,
"configurationPossibleCompliant": 724,
"configurationCompliant": 551
}
],
"success": true,
"statusCode": 200,
"message": "Successfully retrieved vitals data."
}
Understanding Vitals Metrics
The three-stage Vitals validation creates a funnel of compliance:Stage 1: Deployment
├─ agentDeployedPossibleCompliant: 925 devices (should have CrowdStrike)
└─ agentDeployedCompliant: 872 devices (94% deployment rate)
Stage 2: Function
├─ agentFunctioningPossibleCompliant: 872 devices (have agent deployed)
└─ agentFunctioningCompliant: 834 devices (96% functioning rate)
Stage 3: Configuration
├─ configurationPossibleCompliant: 834 devices (have functioning agent)
└─ configurationCompliant: 745 devices (89% configured correctly)
Overall Health = 745/925 = 81% fully compliant
Each stage acts as a filter - devices must pass earlier stages before being checked in later stages.
Use Cases
Executive Dashboards
Build Power BI dashboards showing security posture trends over time
Compliance Evidence
Export historical Vitals data for audit and compliance reporting
Security Metrics
Track security control coverage and health KPIs
Capacity Planning
Identify integrations needing attention or resources
Historical Data
Use thearchiveDate parameter to access historical Vitals data:
# Get Vitals status from August 19, 2024
curl 'https://your-cloud-id.threataware.com/public-api/v1/vitals?archiveDate=20240819' \
-H 'X-ThreatAware-ApiKey: your-api-key-here'
ThreatAware archives Vitals data daily, allowing you to track security posture improvements over time and demonstrate ROI of security initiatives.
Related Documentation
Security Monitoring
Learn about Vitals configuration and thresholds
Devices
Get device-level Vitals status via the devices endpoint