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

> Retrieve data for all teams registered on the platform

## Overview

The Teams endpoint provides access to team definitions and membership within the ThreatAware platform. Teams enable collaborative access to subsets of devices, users, and dashboards.

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

## 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 teams
</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="Team Object">
    <ResponseField name="id" type="string">
      Unique team identifier (GUID)
    </ResponseField>

    <ResponseField name="name" type="string">
      Team name
    </ResponseField>

    <ResponseField name="members" type="array">
      Users who are members of this team

      <Expandable title="Member Object">
        <ResponseField name="username" type="string">
          User email/username
        </ResponseField>

        <ResponseField name="name" type="string">
          First name
        </ResponseField>

        <ResponseField name="surname" type="string">
          Last name
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://your-cloud-id.threataware.com/public-api/v1/settings/usermanagement/teams' \
    --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}/settings/usermanagement/teams",
      headers=headers
  )

  teams = response.json()
  print(f"Retrieved {len(teams['data'])} teams")

  # Example: Find largest team
  if teams['data']:
      largest_team = max(teams['data'], key=lambda t: len(t['members']))
      print(f"Largest team: {largest_team['name']} ({len(largest_team['members'])} members)")
  ```

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

      // Example: List team names and member counts
      response.data.data.forEach(team => {
        console.log(`- ${team.name}: ${team.members.length} members`);
      });
    });
  ```

  ```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/settings/usermanagement/teams" `
      -Headers $Headers `
      -Method Get

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

  # Example: Show team summary
  $Response.data | Select-Object name, @{Name="Members";Expression={$_.members.Count}} | Format-Table
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "offset": 0,
    "limit": 1,
    "total": 10,
    "data": [
      {
        "id": "a84d8017-8705-4c6d-ae73-ea2b87dc9c9c",
        "name": "SecOps",
        "members": [
          {
            "username": "dylan.lloyd@company.com",
            "name": "Dylan",
            "surname": "Lloyd"
          },
          {
            "username": "sara.harris@company.com",
            "name": "Sara",
            "surname": "Harris"
          },
          {
            "username": "julian.edwards@company.com",
            "name": "Julian",
            "surname": "Edwards"
          },
          {
            "username": "brandon.taylor@company.com",
            "name": "Brandon",
            "surname": "Taylor"
          },
          {
            "username": "jacob.roberts@company.com",
            "name": "Jacob",
            "surname": "Roberts"
          },
          {
            "username": "adam.graham@company.com",
            "name": "Adam",
            "surname": "Graham"
          }
        ]
      }
    ],
    "success": true,
    "statusCode": 200,
    "message": "Successfully retrieved teams."
  }
  ```
</ResponseExample>

## Team-Based Access Control

Teams enable delegation of access within ThreatAware:

<AccordionGroup>
  <Accordion title="Device Visibility">
    **Tag-Based Scoping**

    Teams can be scoped to see only devices with specific tags. For example:

    * "IT Service Desk" team sees only devices tagged `IT-Managed`
    * "MSP Client A" team sees only devices tagged `Client-A`

    This scoping is enforced throughout the platform (device views, reports, dashboards, API).
  </Accordion>

  <Accordion title="Saved Views & Dashboards">
    **Team-Shared Resources**

    Teams can share:

    * Device saved views (filtered device lists)
    * User saved views
    * AI Reporting dashboards
    * Reports

    This enables collaboration within teams without sharing to entire organization.
  </Accordion>

  <Accordion title="Alert Assignment">
    **Collaborative Workflows**

    Alerts can be assigned to teams rather than individuals, allowing:

    * Team members to pick up alerts from a shared queue
    * Load balancing across team
    * Coverage during absences
  </Accordion>
</AccordionGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="MSP Client Segmentation" icon="building">
    Create a team per MSP client for isolated access
  </Card>

  <Card title="Department-Based Access" icon="sitemap">
    IT, Security, Compliance teams with scoped visibility
  </Card>

  <Card title="Collaboration Analytics" icon="chart-line">
    Track team membership and access patterns
  </Card>

  <Card title="Onboarding Automation" icon="user-plus">
    Automate team assignment during user onboarding
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Users" icon="users" href="/api-reference/settings-users">
    View user accounts and their team memberships
  </Card>

  <Card title="Get Roles" icon="user-tag" href="/api-reference/settings-roles">
    View role definitions and permissions
  </Card>
</CardGroup>