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

# Get Key Devices

> This method retrieves aggregated device usage for license keys. It returns Key Device objects.

This method retrieves aggregated device usage for license keys. It returns
[Key Device](/api-reference/generated/model/KeyDevice) objects.

### Parameters

This method is accessed by [https://api.cryptolens.io/api/ai/GetKeyDevices](https://api.cryptolens.io/api/ai/GetKeyDevices)

| **Parameter** | **Description** | **Remarks** |
| - | - | - |
| Limit | Specifies how many devices should be returned. | default is 100 and at most 1000 |
| StartingAfter | Works as a forward cursor. If the last result had id=125, setting this to 125 returns results after 125. | optional. Results are ordered by Id ascending. |
| EndingBefore | Works as a backward cursor. If the first result had id=125, setting this to 125 returns results before 125. | optional. Results are ordered by Id descending. If both cursors are supplied, EndingBefore is used. |
| ProductId | The product id to filter on. Required when filtering by the license key string. | optional |
| KeyId | The license key ID to filter on. | optional |
| Key | The license key string to filter on. | optional, requires ProductId |
| MachineCode | The machine code to filter on. | optional, normalized before filtering |
| Start | Only return devices that were active on or after this date. | optional, format yyyy-MM-dd |
| End | Only return devices first seen before the end of this date. | optional, format yyyy-MM-dd |
| token | An access token with Usage Analytics permission. | required |
| v | Method version. | optional. by default, it's 1. |

### Results

| **Parameter** | **Description** | **Remarks** |
| - | - | - |
| Devices | A list of [Key Device](/api-reference/generated/model/KeyDevice) objects. | returned if no errors are thrown |
| Result | This is either **0**(=success) or **1**(=error). | always returned |
| Message | The message that provides additional information about the result. | always returned. |

### Example results

```text theme={null}
{"devices":[{"id":9,"productId":3349,"keyId":123456,"key":"AAAA-BBBB-CCCC-DDDD","machineCode":"MACHINE-1","firstSeenUtc":1748131200,"lastSeenUtc":1748217600,"totalRequests":25}],"result":0,"message":null}
```

### Remarks

* Usage analytics are updated asynchronously, so very recent activity may not appear immediately.
* Only activity with a non-empty machine code is included in key device results.
* Machine codes are normalized for matching: control characters are removed, whitespace is trimmed, values longer than 256 characters are truncated, and the value is uppercased.
* The **Key** field is empty if the license key no longer exists.
* If the access token is locked to a key, only devices for that key can be returned.
* The **MachineCode** filter must match the full normalized machine code.

### Errors

| **Error** |
| - |
| Access denied. |
| The input parameters were incorrect. |
| Could not find the product. |
| Could not find the key. |
| The 'Start' parameter has the wrong format. |
| The 'End' parameter has the wrong format. |