> ## 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 Floating Capacity Licenses

> This method identifies the licenses contributing to excess or unused capacity in a specific 30-minute UTC interval.

This method identifies the licenses contributing to excess or unused capacity in a specific 30-minute UTC interval.

This method requires **Usage Analytics** permission.
Returning customer names, company names, and email addresses also requires **Get Customers** permission.

It returns [capacity license](https://help.cryptolens.io/api-reference/generated/model/ReportResults.md#capacity-license-fields) objects.

### Parameters

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

| **Parameter** | **Description** | **Remarks** |
| - | - | - |
| ProductId | The product containing the licenses. | Required. A positive integer identifying an owned product allowed by the token. |
| IntervalStartUtc | The start of the 30-minute UTC interval. Use WorstIntervalStartUtc from [Get Floating Capacity](https://help.cryptolens.io/api-reference/generated/GetFloatingCapacity.md). | Required. A Unix timestamp in seconds, aligned to a 30-minute boundary and not in the future. |
| CapacityMode | Whether to return licenses with excess or unused capacity. | Optional. Use exceeded (default) or below. Usage must be strictly above or below a positive configured maximum. |
| Page | The page of results to return. | Optional. Default is 1; must be at least 1. |
| Limit | The maximum number of rows to return on this page. | Optional. Default is 100; values above 1000 are capped at 1000. Nonpositive values use the default. |
| token | An access token with Usage Analytics permission. | Required. The account must have analytics access; Free and Hobby tiers are excluded. |
| v | Method version. | Optional. Default is 1. |

### Results

| **Parameter** | **Description** | **Remarks** |
| - | - | - |
| Licenses | A list of [capacity license](https://help.cryptolens.io/api-reference/generated/model/ReportResults.md#capacity-license-fields) objects. | Returned on success. Ordered by absolute capacity difference descending, then key ID ascending. |
| ProductId | The resolved product ID. | An integer. Returned on success. |
| IntervalStartUtc | The requested interval start. | Unix timestamp in seconds. Returned on success. |
| CapacityMode | The resolved capacity mode. | A string: exceeded or below. Returned on success. |
| HasData | Whether the authorized interval contains tracked licenses with positive capacity limits. | A Boolean. Returned on success; can be true even when no licenses match the capacity mode. |
| Page | The resolved page number. | An integer, starting at 1. Returned on success. |
| Limit | The resolved page size. | An integer. Returned on success. |
| Total | The total number of licenses matching the capacity mode within the authorized interval. | An integer, calculated before pagination. Returned on success. |
| Returned | The number of rows returned on this page. | An integer. Returned on success. |
| GeneratedUtc | The UTC time captured for this request. | Unix timestamp in seconds. Returned on success; does not freeze results across requests. |
| Result | This is either **0** (=success) or **1** (=error). | Always returned. |
| Message | Additional information about the result. | A string, or null when there is no message. Always returned. |

### Example results

This response follows the interval from the Get Floating Capacity example. License 12345 has 12 floating machines against a limit of 10. IDs and values are illustrative.

```text theme={null}
{
  "productId": 3349,
  "intervalStartUtc": 1790856000,
  "capacityMode": "exceeded",
  "hasData": true,
  "licenses": [
    {
      "productId": 3349,
      "productName": "Example product",
      "keyId": 12345,
      "key": "AAAA-BBBB-CCCC-DDDD",
      "customerId": null,
      "customerName": null,
      "customerCompany": null,
      "customerEmail": null,
      "floatingMachines": 12,
      "maxNoOfMachines": 10,
      "capacityValue": 2,
      "isCurrent": false,
      "sourceUpdatedUtc": 1790856120
    }
  ],
  "page": 1,
  "limit": 100,
  "total": 1,
  "returned": 1,
  "generatedUtc": 1793102400,
  "result": 0,
  "message": null
}
```

### Remarks

* This method supports GET with query parameters and POST with a form or JSON body. Send the access token in the `token` header, query string, or form field. For JSON requests, use `Content-Type: application/json` and send the token separately; it is not read from the JSON body.
* JSON responses use camel-case field names. All timestamps are Unix seconds in UTC; date strings use `yyyy-MM-dd`.
* An out-of-range page returns an empty list. **Total** counts all rows in the authorized result before pagination; **Returned** counts only this page.
* Product and key locks restrict the result before counting and paging. With a key-locked token, only the authorized key can be returned.
* Only tracked licenses with a positive configured maximum can match. Usage equal to the maximum is excluded in both modes. **CapacityValue** is the signed difference between **FloatingMachines** and **MaxNoOfMachines**.
* **CustomerId** is returned only when the linked customer belongs to the same account. **CustomerName**, **CustomerCompany**, and **CustomerEmail** additionally require the token's Get Customers permission. Missing or disallowed details are null.
* Historical records for deleted licenses may retain product and key IDs with null license details.
* **HasData** is independent of the requested page and capacity mode. An empty **Licenses** list may mean no licenses matched or the page is beyond the results; check **Total** and **HasData**.
* The current interval uses asynchronously maintained current state. Historical intervals restore the last state before the interval end. An untracked state must not be interpreted as zero usage.
* **SourceUpdatedUtc** is the source record's update or recording time. Values do not represent every instantaneous peak, and separate requests may observe background updates.
* To investigate a license further, pass its **ProductId** and **KeyId** to [Get Floating Capacity History](https://help.cryptolens.io/api-reference/generated/GetFloatingCapacityHistory.md).

#### Example request

Replace `YOUR_USAGE_ANALYTICS_TOKEN` and the sample identifiers with your own values. This POST example sends form-encoded parameters.

```text theme={null}
curl -X POST https://api.cryptolens.io/api/ai/GetFloatingCapacityLicenses \
  --data-urlencode "token=YOUR_USAGE_ANALYTICS_TOKEN" \
  --data-urlencode "ProductId=3349" \
  --data-urlencode "IntervalStartUtc=1790856000" \
  --data-urlencode "CapacityMode=exceeded" \
  --data-urlencode "Page=1" \
  --data-urlencode "Limit=100"
```

### Errors

Errors return **Result=1** with an explanation in **Message**. Common errors include:

| **Error** |
| - |
| Access denied. |
| Your subscription does not include access to this method. |
| The input parameters were incorrect. |
| Could not find the product. |
| The page is too large. |
| Could not find the key. |
| ProductId and IntervalStartUtc are required. |
| Invalid IntervalStartUtc. |
| IntervalStartUtc must be a non-future 30-minute UTC boundary in Unix seconds. |
| CapacityMode must be exceeded or below. |

[View the original Web API reference](https://app.cryptolens.io/docs/api/v3/GetFloatingCapacityLicenses)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.