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

> Retrieve all user data that has been collected from your integrations

## Overview

The Users endpoint aggregates user account information from all connected directory services and identity providers (Active Directory, Azure AD, Google Workspace, etc.).

##

Parameters

<ParamField query="filter" type="string" default="all">
  Filter users based on their current 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 users 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="User Object">
    <ResponseField name="name" type="string">
      Full name of the user
    </ResponseField>

    <ResponseField name="email" type="string">
      Email address
    </ResponseField>

    <ResponseField name="jobTitle" type="string">
      Job title
    </ResponseField>

    <ResponseField name="department" type="string">
      Department
    </ResponseField>

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

    <ResponseField name="lastActivity" type="string">
      Last activity timestamp (ISO 8601)
    </ResponseField>

    <ResponseField name="lastSuccessLogin" type="object">
      <Expandable title="Login Details">
        <ResponseField name="lastLoginTime" type="string">
          Timestamp of last successful login
        </ResponseField>

        <ResponseField name="lastLoginLocation" type="object">
          Geographic location of last login (IP, country, city)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="lastFailedLogin" type="object">
      Details of last failed login attempt
    </ResponseField>

    <ResponseField name="recentDevices" type="array">
      List of devices recently used by this user
    </ResponseField>
  </Expandable>
</ResponseField>

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

  response = requests.get(f"{BASE_URL}/users", headers=headers, params={"limit": 10})
  users = response.json()

  print(f"Retrieved {len(users['data'])} of {users['total']} total users")
  ```

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

  const headers = {
    'Accept': 'application/json',
    'X-ThreatAware-ApiKey': API_KEY
  };

  axios.get(`${BASE_URL}/users`, {
    headers,
    params: { limit: 10 }
  })
    .then(response => {
      console.log(`Retrieved ${response.data.data.length} users`);
    });
  ```

  ```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/users?limit=10" -Headers $Headers -Method Get

  Write-Host "Retrieved $($Response.data.Count) of $($Response.total) total users"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "offset": 0,
    "limit": 1,
    "total": 100,
    "data": [
      {
        "name": "Douglas Campbell",
        "email": "douglas.campbell@company.com",
        "jobTitle": "Data Protection Officer",
        "department": "Compliance",
        "tags": [],
        "lastActivity": "0001-01-01T00:00:00.0000000",
        "lastSuccessLogin": {
          "lastLoginTime": "2022-10-08T16:54:03.0000000",
          "lastLoginLocation": {
            "ip": "203.0.113.42",
            "countryCode": "gb",
            "country": "United Kingdom",
            "city": "London"
          }
        },
        "lastFailedLogin": {
          "lastLoginTime": "2022-10-07T04:58:20.0000000",
          "lastLoginLocation": {
            "ip": "203.0.113.99",
            "countryCode": "za",
            "country": "South Africa",
            "city": "Standerton"
          }
        },
        "recentDevices": [
          {
            "itemId": "aceeb28b-95dd-41d9-8880-cd2f33ca965b",
            "name": "LAPTOP-001",
            "multiple": false,
            "isInactive": false
          }
        ]
      }
    ],
    "success": true,
    "statusCode": 200,
    "message": "Successfully retrieved users."
  }
  ```
</ResponseExample>

## Use Cases

<CardGroup cols={2}>
  <Card title="User Access Auditing" icon="user-shield">
    Track which users have accessed which systems and from where
  </Card>

  <Card title="MFA Coverage Reporting" icon="shield-check">
    Identify users without MFA enabled across identity providers
  </Card>

  <Card title="Offboarding Validation" icon="user-minus">
    Verify user account deactivation across all connected systems
  </Card>

  <Card title="Geographic Access Analysis" icon="globe">
    Monitor login patterns and detect unusual geographic access
  </Card>
</CardGroup>