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

> Access all your data related to your environment's devices

## Overview

The Devices endpoint provides access to ThreatAware's unified device inventory, aggregating data from all connected integrations. This is the primary endpoint for device information.

## Parameters

<ParamField query="filter" type="string" required>
  Filter devices based on their current state

  **Options:**

  * `active` - Devices online within threshold (default 30 days)
  * `inactive` - Devices offline longer than threshold
  * `all` - All devices regardless of state
</ParamField>

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

## 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 devices available
</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="Device Object">
    <ResponseField name="hostName" type="string">
      Device hostname
    </ResponseField>

    <ResponseField name="os" type="string">
      Operating system (Windows, macOS, Linux, iOS, Android)
    </ResponseField>

    <ResponseField name="osVersion" type="string">
      Operating system version
    </ResponseField>

    <ResponseField name="lastOnline" type="string">
      Timestamp device was last seen online (ISO 8601)
    </ResponseField>

    <ResponseField name="location" type="object">
      <Expandable title="Geographic Location">
        <ResponseField name="countryCode" type="string">
          Two-letter country code
        </ResponseField>

        <ResponseField name="country" type="string">
          Country name
        </ResponseField>

        <ResponseField name="city" type="string">
          City name
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="tags" type="array">
      Tags assigned to this device
    </ResponseField>

    <ResponseField name="metadata" type="object">
      <Expandable title="Hardware Details">
        <ResponseField name="serial_number" type="string">
          Device serial number
        </ResponseField>

        <ResponseField name="manufacturer" type="string">
          Hardware manufacturer (e.g., Dell, HP, Apple)
        </ResponseField>

        <ResponseField name="model" type="string">
          Device model
        </ResponseField>

        <ResponseField name="total_disk_storage" type="string">
          Total disk space
        </ResponseField>

        <ResponseField name="free_disk_storage" type="string">
          Available disk space
        </ResponseField>

        <ResponseField name="total_memory" type="string">
          Total RAM
        </ResponseField>

        <ResponseField name="cpu_speed" type="string">
          CPU speed
        </ResponseField>

        <ResponseField name="warranty_expiry" type="string">
          Warranty expiration date
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="lastUser" type="object">
      Last user to log into this device
    </ResponseField>

    <ResponseField name="lastLogin" type="string">
      Timestamp of last user login
    </ResponseField>

    <ResponseField name="publicIp" type="string">
      Public IP address
    </ResponseField>

    <ResponseField name="privateIp" type="string">
      Private IP address
    </ResponseField>

    <ResponseField name="macAddress" type="string">
      MAC address
    </ResponseField>

    <ResponseField name="securityTools" type="array">
      Security controls deployed on this device with alert counts
    </ResponseField>

    <ResponseField name="connectedSystems" type="array">
      Integrations where this device is present
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://your-cloud-id.threataware.com/public-api/v1/devices?filter=active&limit=10' \
    --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
  }

  params = {
      "filter": "active",
      "limit": 10
  }

  response = requests.get(f"{BASE_URL}/devices", headers=headers, params=params)
  devices = response.json()

  print(f"Retrieved {len(devices['data'])} active devices")

  # Example: Find Windows devices
  windows_devices = [d for d in devices['data'] if d['os'] == 'Windows']
  print(f"Windows devices: {len(windows_devices)}")
  ```

  ```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}/devices`, {
    headers: {
      'Accept': 'application/json',
      'X-ThreatAware-ApiKey': API_KEY
    },
    params: {
      filter: 'active',
      limit: 10
    }
  })
    .then(response => {
      console.log(`Retrieved ${response.data.data.length} active devices`);

      // Example: Filter by OS
      const macDevices = response.data.data.filter(d => d.os === 'macOS');
      console.log(`macOS devices: ${macDevices.length}`);
    });
  ```

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

  $Params = @{
      filter = "active"
      limit = 10
  }

  $Response = Invoke-RestMethod -Uri "$BaseUrl/devices" -Headers $Headers -Body $Params -Method Get

  Write-Host "Retrieved $($Response.data.Count) active devices"

  # Example: Group by OS
  $Response.data | Group-Object -Property os | Format-Table Name, Count
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "offset": 0,
    "limit": 1,
    "total": 100,
    "data": [
      {
        "hostName": "LAPTOP-001-FJ23Y",
        "os": "Windows",
        "osVersion": "Windows 11",
        "lastOnline": "2022-10-10T08:49:28.0000000",
        "location": {
          "countryCode": "gb",
          "country": "United Kingdom",
          "city": "London"
        },
        "tags": [],
        "metadata": {
          "warranty_expiry": "2022-10-10 08:33:18",
          "serial_number": "F11929BD2CF8",
          "total_disk_storage": "230 GB",
          "free_disk_storage": "31 GB",
          "total_memory": "32 GB",
          "cpu_speed": "2.91 GHz",
          "model": "XPS 13",
          "manufacturer": "Dell"
        },
        "lastUser": {
          "name": "Douglas Campbell",
          "email": "douglas.campbell@company.com"
        },
        "lastLogin": "2022-10-10T08:49:28.0000000",
        "publicIp": "203.0.113.42",
        "privateIp": "198.51.100.17",
        "macAddress": "02:00:5E:00:53:01",
        "securityTools": [
          {
            "name": "Automox",
            "redAlerts": 0,
            "amberAlerts": 1
          },
          {
            "name": "Bitdefender",
            "redAlerts": 0,
            "amberAlerts": 0
          },
          {
            "name": "Cisco Umbrella",
            "redAlerts": 0,
            "amberAlerts": 1
          }
        ],
        "connectedSystems": [
          {
            "name": "Tenable IO",
            "isConnected": true,
            "isActive": true
          },
          {
            "name": "Azure AD",
            "isConnected": true,
            "isActive": true
          },
          {
            "name": "Teamviewer",
            "isConnected": true,
            "isActive": true
          }
        ]
      }
    ],
    "success": true,
    "statusCode": 200,
    "message": "Successfully retrieved devices."
  }
  ```
</ResponseExample>

## Use Cases

<CardGroup cols={2}>
  <Card title="CMDB Synchronization" icon="database">
    Export device inventory to ServiceNow, Jira, or other CMDBs
  </Card>

  <Card title="Security Dashboards" icon="chart-line">
    Build Power BI, Tableau, or custom dashboards from device data
  </Card>

  <Card title="Asset Management" icon="boxes-stacked">
    Track hardware lifecycle, warranty status, and replacement planning
  </Card>

  <Card title="Compliance Reporting" icon="file-shield">
    Generate device compliance reports for audits and certifications
  </Card>
</CardGroup>

## Related Endpoints

<Card title="Vitals" icon="heartbeat" href="/api-reference/vitals">
  Get security control health status for devices
</Card>