Skip to content

Endpoints in group

GET/endpoint-groups/{groupId}/endpoints

Endpoint API · Endpoint Groups Management

Returns the endpoints in your specified group.

Required permissionendpoint-groups:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
groupId path string (uuid) Yes Endpoint group ID.
sort query array of string No Defines how to sort the data. We are temporarily stopping support for this parameter until further notice.
Each item must match the pattern (^[^:]+$)|(^[^:]+:(asc|desc)$).
fields query array of string No The fields to return in a partial response.
pageFromKey query string No The key of the item from where to fetch a page.
pageTotal query boolean No Whether the number of pages should be calculated and returned in the response.
pageSize query integer No The size of the page requested.
Must be ≥ 1 and ≤ 500.
search query string No Term to search for in the specified search fields. We are temporarily stopping support for this parameter until further notice.
searchFields query array of string No List of search fields for finding the given search term. Defaults to all applicable fields. We are temporarily stopping support for this parameter until further notice.
Each item must be one of: hostname, groupName, associatedPersonName, ipAddresses, osName.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups/<groupId>/endpoints" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups/<groupId>/endpoints",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups/<groupId>/endpoints" -Headers $headers


package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups/<groupId>/endpoints", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/endpoint/v1/endpoint-groups/<groupId>/endpoints", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — A page of endpoints.

Response fields

itemsarray of objectrequired
List of endpoints.
Show child attributesHide child attributes
idstring (uuid)required
Unique ID for the endpoint.
typestringrequired
Endpoint type. Please note that the type securityVm is no longer used.
Must be one of: computer, server, securityVm.
tenantobject
Represents a referenced object.
Show child attributesHide child attributes
idstring (uuid)required
The ID of the referenced object.
hostnamestringrequired
Hostname of the endpoint.
healthobject
Health status of an endpoint.
Show child attributesHide child attributes
overallstringrequired
Health status of an endpoint or a service running on an endpoint.
Must be one of: good, suspicious, bad, unknown.
threatsobjectrequired
Threats on the endpoint.
Show child attributesHide child attributes
statusstringrequired
Health status of an endpoint or a service running on an endpoint.
Must be one of: good, suspicious, bad, unknown.
servicesobjectrequired
Status of services on the endpoint.
Show child attributesHide child attributes
statusstringrequired
Health status of an endpoint or a service running on an endpoint.
Must be one of: good, suspicious, bad, unknown.
serviceDetailsarray of objectrequired
Details of services on the endpoint.
Show child attributesHide child attributes
namestringrequired
Service name.
statusstringrequired
Status of a service on an endpoint.
Must be one of: running, stopped, missing.
osobjectrequired
OS information.
Show child attributesHide child attributes
isServerboolean
Whether the OS is a server OS.
platformstringrequired
OS platform type.
Must be one of: windows, linux, macOS.
namestringrequired
OS name as reported by the endpoint.
majorVersioninteger
OS major version.
minorVersioninteger
OS minor version.
buildinteger
OS build.
ipv4Addressesarray of string
List of IPv4 addresses.
ipv6Addressesarray of string
List of IPv6 addresses.
macAddressesarray of string
List of MAC addresses.
groupobject
Endpoint group.
Show child attributesHide child attributes
namestring
Endpoint group name.
idstring (uuid)
Unique ID for endpoint group.
groupHierarchyarray of object
List of groups in the hierarchy, starting with the group the endpoint is in and ending with the top-level group.
A single group in the endpoint group hierarchy.
Show child attributesHide child attributes
namestringrequired
Endpoint group name.
idstring (uuid)required
Unique ID for endpoint group.
parentIdstring (uuid)
Unique ID of the parent group. Omitted for the top-level group.
associatedPersonobject
Person associated with an endpoint.
Show child attributesHide child attributes
namestring
Person's name.
viaLoginstring
Person's login on the endpoint.
idstring (uuid)
Unique ID for the Person.
tamperProtectionSupportedboolean
Whether the endpoint supports Tamper Protection.
tamperProtectionEnabledboolean
Whether Tamper Protection is turned on.
assignedProductsarray of object
Products assigned to the endpoint.
Show child attributesHide child attributes
codestringrequired
Endpoint product.
Must be one of: coreAgent, interceptX, xdr, endpointProtection, deviceEncryption, mtr, ztna.
versionstringrequired
Version of a product assigned to an endpoint.
statusstring
Installation status of a product assigned to the endpoint.
Must be one of: installed, notInstalled.
packagesobject
Choice of device software available to the endpoint.
Show child attributesHide child attributes
protectionobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
ztnaobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
encryptionobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
deviceSoftwareobject
Choice of device software available to the endpoint.
Show child attributesHide child attributes
protectionobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
ztnaobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
encryptionobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
lastSeenAtstring
Date and time (UTC) when the endpoint last communicated with Sophos Central.
lastOsUpdateAtstring
Date and time (UTC) when the endpoint last applied an operating system update.
serialNumberstring
The hardware/BIOS serial number of the endpoint. Only Mac endpoints report their serial number currently.
encryptionobject
Endpoint encryption state.
Show child attributesHide child attributes
volumesarray of objectrequired
Endpoint volumes.
Endpoint volume encryption status.
Show child attributesHide child attributes
volumeIdstringrequired
Endpoint volume ID.
statusstringrequired
Endpoint volume encryption status.
Must be one of: notEncrypted, encrypted, encrypting, notSupported, suspended, unknown.
overallStatusstring
The overall encryption status of the endpoint.
Must be one of: notEncrypted, encrypted, encrypting, notSupported, suspended, notAvailable, unmanaged.
lockdownobject
Server Lockdown status.
Show child attributesHide child attributes
statusstringrequired
Server lockdown status. Please note that the following statuses are no longer used: creatingWhitelist, installing, registering, and starting are now reported as locking; stopping is reported as locked; and uninstalled is reported as unlocked.
Must be one of: creatingWhitelist, installing, locked, notInstalled, registering, starting, stopping, unavailable, uninstalled, unlocked, locking.
tagsarray of object
List of tags.
Must contain at most 15 items.
Tagging object that can be applied to multiple types of devices or other objects.
Show child attributesHide child attributes
keystringrequired
A tag key. Between 1 and 40 characters which must not include colons.
Must match the pattern ^[^:]{1,40}$.
valuestringrequired
A tag value between 0 and 40 characters which must not include colons.
Must match the pattern ^[^:]{0,40}$.
displayStringstring
A tag display string.
Must match the pattern ^([^:]{1,40}):([^:]{0,40})$.
tagOriginstring
The origin of the tag.
vendorNamestring
The name of the third-party vendor associated with the tag.
onlineboolean
Whether endpoint is currently online.
cloudobject
Endpoint cloud.
Show child attributesHide child attributes
providerstringrequired
Cloud provider in which the endpoint is running.
Must be one of: aws, azure.
instanceIdstringrequired
Unique ID for the cloud instance.
Must match the pattern ^([0-9a-zA-Z-_]{1,64}).
isolationobject
Endpoint isolation state as reported by an endpoint.
Show child attributesHide child attributes
statusstringrequired
Isolation status reported by endpoint.
Must be one of: isolated, notIsolated.
adminIsolatedboolean
Whether isolation was triggered by an admin.
selfIsolatedboolean
Whether isolation was triggered by the endpoint itself.
clonedboolean
Whether the endpoint has been cloned by another endpoint.
lastAgentUpdateAtstring
Date and time (UTC) when the agent was last successfully updated.
pagesobjectrequired
Show child attributesHide child attributes
fromKeystring
The key of the first item in the returned page.
nextKeystring
The key to use when fetching the next page.
sizeintegerrequired
The size of the page being returned.
totalinteger
(Optional) The total number of pages that exist, if pageTotal=true in the request.
itemsinteger
(Optional) The total number of items on all the pages, if pageTotal=true was passed into the request.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
404 Group not found.
500 Internal server error.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "computer",
      "tenant": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "hostname": "string",
      "health": {
        "overall": "good",
        "threats": {
          "status": "good"
        },
        "services": {
          "status": "good",
          "serviceDetails": [
            {
              "name": "string",
              "status": "running"
            }
          ]
        }
      },
      "os": {
        "isServer": true,
        "platform": "windows",
        "name": "string",
        "majorVersion": 0,
        "minorVersion": 0,
        "build": 0
      },
      "ipv4Addresses": [
        "string"
      ],
      "ipv6Addresses": [
        "string"
      ],
      "macAddresses": [
        "string"
      ],
      "group": {
        "name": "string",
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "groupHierarchy": [
        {
          "name": "Data Team",
          "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "parentId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
        },
        {
          "name": "Backend Team",
          "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "parentId": "550e8400-e29b-41d4-a716-446655440000"
        },
        {
          "name": "Engineering",
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "associatedPerson": {
        "name": "string",
        "viaLogin": "string",
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "tamperProtectionSupported": true,
      "tamperProtectionEnabled": true,
      "assignedProducts": [
        {
          "code": "coreAgent",
          "version": "string",
          "status": "installed"
        }
      ],
      "packages": {
        "protection": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        },
        "ztna": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        },
        "encryption": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        }
      },
      "deviceSoftware": {
        "protection": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        },
        "ztna": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        },
        "encryption": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        }
      },
      "lastSeenAt": "2019-09-23T12:02:01.700Z",
      "lastOsUpdateAt": "2025-02-23T12:02:01.700Z",
      "serialNumber": "P28DA81LMD5T",
      "encryption": {
        "volumes": [
          {
            "volumeId": "string",
            "status": "notEncrypted"
          }
        ],
        "overallStatus": "notEncrypted"
      },
      "lockdown": {
        "status": "creatingWhitelist"
      },
      "tags": [
        {
          "key": "string",
          "value": "string",
          "displayString": "string",
          "tagOrigin": "string",
          "vendorName": "string"
        }
      ],
      "online": true,
      "cloud": {
        "provider": "aws",
        "instanceId": "string"
      },
      "isolation": {
        "status": "isolated",
        "adminIsolated": true,
        "selfIsolated": true
      },
      "cloned": true,
      "lastAgentUpdateAt": "2019-09-23T12:02:01.700Z"
    }
  ],
  "pages": {
    "fromKey": "string",
    "nextKey": "string",
    "size": 0,
    "total": 0,
    "items": 0,
    "maxSize": 0
  }
}

See the guide for a narrative walkthrough of this API.