> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List devices for an entity

> List all devices linked to an entity in gu1 — returns fingerprints, metadata, and last-seen timestamps for fraud prevention and audit trails.

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="entityId" type="string" required>
  UUID of the entity whose devices you want to retrieve
</ParamField>

## Query Parameters

<ParamField query="limit" type="number" default="50">
  Maximum number of devices to return per page (max: 1000)

  Example: `?limit=100`
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of devices to skip for pagination

  Example: `?offset=50`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="devices" type="array">
  Array of device objects sorted by `lastSeenAt` (most recent first)

  <ResponseField name="devices[].id" type="string">
    gu1's internal device UUID
  </ResponseField>

  <ResponseField name="devices[].deviceId" type="string">
    Device identifier
  </ResponseField>

  <ResponseField name="devices[].externalId" type="string">
    External device identifier
  </ResponseField>

  <ResponseField name="devices[].entityId" type="string">
    UUID of the associated entity
  </ResponseField>

  <ResponseField name="devices[].entityExternalId" type="string">
    Entity's external ID (denormalized)
  </ResponseField>

  <ResponseField name="devices[].entityTaxId" type="string">
    Entity's tax ID (denormalized)
  </ResponseField>

  <ResponseField name="devices[].deviceName" type="string">
    User-defined device name or hardware name
  </ResponseField>

  <ResponseField name="devices[].deviceDetails" type="object">
    Additional device metadata (JSON object). Platform-specific details.
  </ResponseField>

  <ResponseField name="devices[].platform" type="string">
    Device platform (android, ios, web)
  </ResponseField>

  <ResponseField name="devices[].manufacturer" type="string">
    Device manufacturer
  </ResponseField>

  <ResponseField name="devices[].model" type="string">
    Device model
  </ResponseField>

  <ResponseField name="devices[].brand" type="string">
    Device brand
  </ResponseField>

  <ResponseField name="devices[].osName" type="string">
    Operating system name
  </ResponseField>

  <ResponseField name="devices[].osVersion" type="string">
    Operating system version
  </ResponseField>

  <ResponseField name="devices[].browser" type="string">
    Browser name (web only)
  </ResponseField>

  <ResponseField name="devices[].browserVersion" type="string">
    Browser version (web only)
  </ResponseField>

  <ResponseField name="devices[].latitude" type="number">
    Geographic latitude
  </ResponseField>

  <ResponseField name="devices[].longitude" type="number">
    Geographic longitude
  </ResponseField>

  <ResponseField name="devices[].city" type="string">
    City name
  </ResponseField>

  <ResponseField name="devices[].region" type="string">
    State/province
  </ResponseField>

  <ResponseField name="devices[].country" type="string">
    Country name
  </ResponseField>

  <ResponseField name="devices[].countryCode" type="string">
    ISO country code
  </ResponseField>

  <ResponseField name="devices[].ipAddress" type="string">
    Last known IP address
  </ResponseField>

  <ResponseField name="devices[].isEmulator" type="boolean">
    Whether device is an emulator
  </ResponseField>

  <ResponseField name="devices[].isRooted" type="boolean">
    Whether device is rooted/jailbroken
  </ResponseField>

  <ResponseField name="devices[].isBlocked" type="boolean">
    Whether device is blocked
  </ResponseField>

  <ResponseField name="devices[].isTrusted" type="boolean">
    Whether device is trusted
  </ResponseField>

  <ResponseField name="devices[].firstSeenAt" type="string">
    First seen timestamp (ISO 8601)
  </ResponseField>

  <ResponseField name="devices[].lastSeenAt" type="string">
    Last seen timestamp (ISO 8601)
  </ResponseField>

  <ResponseField name="devices[].createdAt" type="string">
    Creation timestamp
  </ResponseField>

  <ResponseField name="devices[].updatedAt" type="string">
    Last update timestamp
  </ResponseField>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information

  <ResponseField name="pagination.total" type="number">
    Total number of devices for this entity
  </ResponseField>

  <ResponseField name="pagination.limit" type="number">
    Page size limit used
  </ResponseField>

  <ResponseField name="pagination.offset" type="number">
    Offset used
  </ResponseField>

  <ResponseField name="pagination.hasMore" type="boolean">
    Whether there are more pages available
  </ResponseField>
</ResponseField>

## Examples

### Basic Query

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

### With Pagination

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000?limit=20&offset=0" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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`);
  ```

  ```python Python theme={null}
  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")
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to read devices"
  }
}
```

### 404 Not Found

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

### 500 Internal Server Error

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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

```javascript theme={null}
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;
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Device" icon="plus" href="/en/api-reference/devices/create">
    Register a new device
  </Card>

  <Card title="Events API" icon="bolt" href="/en/api-reference/events/overview">
    Learn about automatic device registration
  </Card>

  <Card title="Fraud Detection" icon="shield-check" href="/en/use-cases/transaction-monitoring/fraud-detection">
    Build device-based fraud rules
  </Card>

  <Card title="Risk Matrix" icon="table-cells" href="/en/api-reference/risk-matrix/list">
    Configure risk scoring with device data
  </Card>
</CardGroup>