> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threataware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Vitals

> Retrieve security control health status across all integrations

## Overview

The Vitals endpoint provides access to security control health data, showing deployment, functionality, and configuration status for all Vitals-enabled integrations.

<Info>
  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.
</Info>

## Parameters

<ParamField query="offset" type="number" default="0">
  Set the start position of the data returned by the API
</ParamField>

<ParamField query="limit" type="number" default="0">
  Limit each request by the provided number. Leave blank or as 0 to return all data available
</ParamField>

<ParamField query="tag" type="string">
  Filter the data down to a specific tag. Blank by default, will return all data.
</ParamField>

<ParamField query="archiveDate" type="string">
  Retrieve archived historical data. Format: `yyyyMMdd` (e.g., `20240819` for August 19, 2024)

  <Tip>
    Use this parameter to track Vitals health over time for trend analysis and reporting.
  </Tip>
</ParamField>

## Authentication

<ParamField header="X-ThreatAware-ApiKey" type="string" required>
  Your ThreatAware API key
</ParamField>

<ParamField header="Accept" type="string" default="application/json">
  Response format
</ParamField>

## Response

<ResponseField name="offset" type="number">
  The starting position of this result set
</ResponseField>

<ResponseField name="limit" type="number">
  The number of results returned
</ResponseField>

<ResponseField name="total" type="number">
  Total number of integrations
</ResponseField>

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="statusCode" type="number">
  HTTP status code
</ResponseField>

<ResponseField name="message" type="string">
  Status message
</ResponseField>

<ResponseField name="data" type="array">
  <Expandable title="Vitals Object">
    <ResponseField name="key" type="string">
      Integration key (e.g., `crowdstrike`, `jamf`, `msdefenderatp`)
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable integration name
    </ResponseField>

    <ResponseField name="vitalsEnabled" type="boolean">
      Whether Vitals monitoring is enabled for this integration
    </ResponseField>

    <ResponseField name="activeAgents" type="number">
      Total number of devices with this integration (when Vitals not enabled)
    </ResponseField>

    **The following fields are only present when `vitalsEnabled` is `true`:**

    <ResponseField name="agentDeployedPossibleCompliant" type="number">
      Number of devices that **should** have this control deployed (based on tags)
    </ResponseField>

    <ResponseField name="agentDeployedCompliant" type="number">
      Number of devices where the agent is **successfully deployed**
    </ResponseField>

    <ResponseField name="agentFunctioningPossibleCompliant" type="number">
      Number of devices with agent deployed (input to Function check)
    </ResponseField>

    <ResponseField name="agentFunctioningCompliant" type="number">
      Number of devices where the agent is **functioning correctly**
    </ResponseField>

    <ResponseField name="configurationPossibleCompliant" type="number">
      Number of devices with functioning agent (input to Configuration check)
    </ResponseField>

    <ResponseField name="configurationCompliant" type="number">
      Number of devices where the agent is **correctly configured**
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://your-cloud-id.threataware.com/public-api/v1/vitals' \
    --header 'Accept: application/json' \
    --header 'X-ThreatAware-ApiKey: your-api-key-here'
  ```

  ```python Python theme={null}
  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")
  ```

  ```javascript Node.js theme={null}
  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`);
    });
  ```

  ```powershell PowerShell theme={null}
  $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"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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."
  }
  ```
</ResponseExample>

## 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
```

<Info>
  Each stage acts as a filter - devices must pass earlier stages before being checked in later stages.
</Info>

## Use Cases

<CardGroup cols={2}>
  <Card title="Executive Dashboards" icon="chart-line">
    Build Power BI dashboards showing security posture trends over time
  </Card>

  <Card title="Compliance Evidence" icon="file-shield">
    Export historical Vitals data for audit and compliance reporting
  </Card>

  <Card title="Security Metrics" icon="gauge-high">
    Track security control coverage and health KPIs
  </Card>

  <Card title="Capacity Planning" icon="chart-network">
    Identify integrations needing attention or resources
  </Card>
</CardGroup>

## Historical Data

Use the `archiveDate` parameter to access historical Vitals data:

```bash theme={null}
# 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'
```

<Tip>
  ThreatAware archives Vitals data daily, allowing you to track security posture improvements over time and demonstrate ROI of security initiatives.
</Tip>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Security Monitoring" icon="heartbeat" href="/security-monitoring">
    Learn about Vitals configuration and thresholds
  </Card>

  <Card title="Devices" icon="laptop" href="/api-reference/devices">
    Get device-level Vitals status via the devices endpoint
  </Card>
</CardGroup>