List devices for an entity

curl --request GET \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/devices/entity/{entityId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/devices/entity/{entityId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "http://api.gu1.ai/devices/entity/{entityId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/devices/entity/{entityId}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "devices": [
    {
      "devices[].id": "<string>",
      "devices[].deviceId": "<string>",
      "devices[].externalId": "<string>",
      "devices[].entityId": "<string>",
      "devices[].entityExternalId": "<string>",
      "devices[].entityTaxId": "<string>",
      "devices[].deviceName": "<string>",
      "devices[].deviceDetails": {},
      "devices[].platform": "<string>",
      "devices[].manufacturer": "<string>",
      "devices[].model": "<string>",
      "devices[].brand": "<string>",
      "devices[].osName": "<string>",
      "devices[].osVersion": "<string>",
      "devices[].browser": "<string>",
      "devices[].browserVersion": "<string>",
      "devices[].latitude": 123,
      "devices[].longitude": 123,
      "devices[].city": "<string>",
      "devices[].region": "<string>",
      "devices[].country": "<string>",
      "devices[].countryCode": "<string>",
      "devices[].ipAddress": "<string>",
      "devices[].isEmulator": true,
      "devices[].isRooted": true,
      "devices[].isBlocked": true,
      "devices[].isTrusted": true,
      "devices[].firstSeenAt": "<string>",
      "devices[].lastSeenAt": "<string>",
      "devices[].createdAt": "<string>",
      "devices[].updatedAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

GET

devices

entity

{entityId}

List devices for an entity

curl --request GET \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/devices/entity/{entityId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/devices/entity/{entityId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "http://api.gu1.ai/devices/entity/{entityId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/devices/entity/{entityId}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "devices": [
    {
      "devices[].id": "<string>",
      "devices[].deviceId": "<string>",
      "devices[].externalId": "<string>",
      "devices[].entityId": "<string>",
      "devices[].entityExternalId": "<string>",
      "devices[].entityTaxId": "<string>",
      "devices[].deviceName": "<string>",
      "devices[].deviceDetails": {},
      "devices[].platform": "<string>",
      "devices[].manufacturer": "<string>",
      "devices[].model": "<string>",
      "devices[].brand": "<string>",
      "devices[].osName": "<string>",
      "devices[].osVersion": "<string>",
      "devices[].browser": "<string>",
      "devices[].browserVersion": "<string>",
      "devices[].latitude": 123,
      "devices[].longitude": 123,
      "devices[].city": "<string>",
      "devices[].region": "<string>",
      "devices[].country": "<string>",
      "devices[].countryCode": "<string>",
      "devices[].ipAddress": "<string>",
      "devices[].isEmulator": true,
      "devices[].isRooted": true,
      "devices[].isBlocked": true,
      "devices[].isTrusted": true,
      "devices[].firstSeenAt": "<string>",
      "devices[].lastSeenAt": "<string>",
      "devices[].createdAt": "<string>",
      "devices[].updatedAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

Overview

Retrieves all devices registered to a specific entity, sorted by last activity. Use this endpoint to monitor device usage patterns, detect suspicious access, and build device-based fraud detection rules.

Endpoint

GET https://api.gu1.ai/devices/entity/{entityId}

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

UUID of the entity whose devices you want to retrieve

Query Parameters

number

default:"50"

Maximum number of devices to return per page (max: 1000)Example: ?limit=100

number

default:"0"

Number of devices to skip for paginationExample: ?offset=50

Investigation context

To retrieve devices grouped by the investigated entity and, optionally, its directly related entities, use:

GET /devices/entity/{entityId}/investigation-context?includeRelatedEntities=true

When true, includes devices from active direct relationships in either direction. All entities, relationships, and devices remain scoped to the authenticated organization.

The response returns totalDevices and an entities array. Each entity includes id, externalId, name, type, isPrimary, relationshipTypes, and its devices array. Related entities without devices are omitted; the primary entity is always returned.

Response

boolean

Indicates if the request was successful

array

Array of device objects sorted by lastSeenAt (most recent first)

string

gu1’s internal device UUID

string

Device identifier

string

External device identifier

string

UUID of the associated entity

string

Entity’s external ID (denormalized)

string

Entity’s tax ID (denormalized)

string

User-defined device name or hardware name

object

Additional device metadata (JSON object). Platform-specific details.

string

Device platform (android, ios, web)

string

Device manufacturer

string

Device model

string

Device brand

string

Operating system name

string

Operating system version

string

Browser name (web only)

string

Browser version (web only)

number

Geographic latitude

number

Geographic longitude

string

City name

string

State/province

string

Country name

string

ISO country code

string

Last known IP address

boolean

Whether device is an emulator

boolean

Whether device is rooted/jailbroken

boolean

Whether device is blocked

boolean

Whether device is trusted

string

First seen timestamp (ISO 8601)

string

Last seen timestamp (ISO 8601)

string

Creation timestamp

string

Last update timestamp

object

Pagination information

number

Total number of devices for this entity

number

Page size limit used

number

Offset used

boolean

Whether there are more pages available

Examples

Basic Query

curl https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data.devices);

import requests

response = requests.get(
    'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

data = response.json()
print(data['devices'])

With Pagination

curl "https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000?limit=20&offset=0',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Page 1 of ${Math.ceil(data.pagination.total / 20)} pages`);

import requests

response = requests.get(
    'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'limit': 20, 'offset': 0}
)

data = response.json()
print(f"Page 1 of {data['pagination']['total'] // 20 + 1} pages")

Response Example

{
  "success": true,
  "devices": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "deviceId": "840e89e4d46efd67",
      "externalId": "840e89e4d46efd67",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityExternalId": "user_12345",
      "entityTaxId": "20-12345678-9",
      "deviceName": "Galaxy A15",
      "deviceDetails": {},
      "platform": "android",
      "manufacturer": "samsung",
      "model": "SM-A156M",
      "brand": "samsung",
      "osName": "Android",
      "osVersion": "Android 16",
      "browser": null,
      "browserVersion": null,
      "latitude": -34.6037,
      "longitude": -58.3816,
      "city": "Buenos Aires",
      "region": "Buenos Aires",
      "country": "Argentina",
      "countryCode": "AR",
      "ipAddress": "10.40.64.231",
      "isEmulator": false,
      "isRooted": false,
      "isBlocked": false,
      "isTrusted": true,
      "firstSeenAt": "2026-01-20T10:00:00Z",
      "lastSeenAt": "2026-01-30T14:30:00Z",
      "createdAt": "2026-01-20T10:00:00Z",
      "updatedAt": "2026-01-30T14:30:00Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "deviceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityExternalId": "user_12345",
      "entityTaxId": null,
      "deviceName": null,
      "deviceDetails": {},
      "platform": "web",
      "manufacturer": null,
      "model": null,
      "brand": null,
      "osName": "Windows",
      "osVersion": null,
      "browser": "Chrome",
      "browserVersion": "120.0.6099.129",
      "latitude": -34.6037,
      "longitude": -58.3816,
      "city": "Buenos Aires",
      "region": "Buenos Aires",
      "country": "Argentina",
      "countryCode": "AR",
      "ipAddress": "10.40.64.231",
      "isEmulator": false,
      "isRooted": false,
      "isBlocked": false,
      "isTrusted": false,
      "firstSeenAt": "2026-01-25T08:15:00Z",
      "lastSeenAt": "2026-01-30T12:00:00Z",
      "createdAt": "2026-01-25T08:15:00Z",
      "updatedAt": "2026-01-30T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to read devices"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "DEVICES_FETCH_FAILED",
    "message": "Failed to fetch entity devices"
  }
}

Use Cases

Device Inventory Dashboard

Build a dashboard showing all devices used by your entities:

async function getDeviceInventory(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Group by platform
  const byPlatform = data.devices.reduce((acc, device) => {
    acc[device.platform] = (acc[device.platform] || 0) + 1;
    return acc;
  }, {});

  console.log('Devices by platform:', byPlatform);
  return data.devices;
}

Fraud Detection

Detect suspicious device patterns:

async function detectSuspiciousDevices(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Flag suspicious devices
  const suspicious = data.devices.filter(device =>
    device.isEmulator ||
    device.isRooted ||
    device.isBlocked
  );

  if (suspicious.length > 0) {
    console.warn('Found suspicious devices:', suspicious);
  }

  return suspicious;
}

Geographic Analysis

Analyze device locations for anomalies:

async function analyzeDeviceLocations(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Get unique countries
  const countries = new Set(
    data.devices.map(d => d.countryCode).filter(Boolean)
  );

  // Flag if devices from multiple countries
  if (countries.size > 1) {
    console.warn('Devices from multiple countries:', Array.from(countries));
  }

  return Array.from(countries);
}

Activity Monitoring

Monitor recent device activity:

async function getRecentDevices(entityId, hours = 24) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();
  const cutoff = new Date(Date.now() - hours * 60 * 60 * 1000);

  // Filter devices active in last N hours
  const recentDevices = data.devices.filter(device =>
    new Date(device.lastSeenAt) > cutoff
  );

  console.log(`${recentDevices.length} devices active in last ${hours} hours`);
  return recentDevices;
}

Pagination Best Practices

Iterate Through All Pages

async function getAllDevices(entityId) {
  const allDevices = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.gu1.ai/devices/entity/${entityId}?limit=${limit}&offset=${offset}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    const data = await response.json();
    allDevices.push(...data.devices);

    hasMore = data.pagination.hasMore;
    offset += limit;
  }

  console.log(`Total devices: ${allDevices.length}`);
  return allDevices;
}

​Overview

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Investigation context

​Response

​Examples

​Basic Query

​With Pagination

​Response Example

​Error Responses

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Use Cases

​Device Inventory Dashboard

​Fraud Detection

​Geographic Analysis

​Activity Monitoring

​Pagination Best Practices

​Iterate Through All Pages

​Next Steps

Create Device

Events API

Fraud Detection

Risk Matrix

Overview

Endpoint

Authentication

Path Parameters

Query Parameters

Investigation context

Response

Examples

Basic Query

With Pagination

Response Example

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Use Cases

Device Inventory Dashboard

Fraud Detection

Geographic Analysis

Activity Monitoring

Pagination Best Practices

Iterate Through All Pages

Next Steps