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

> This method identifies products and periods with excess or unused floating-license capacity using the same tracked state as the Devolens floating capacity dashboard.

This method identifies products and periods with excess or unused floating-license capacity using the same tracked state as the Devolens floating capacity dashboard.

This method requires **Usage Analytics** permission.

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

### Parameters

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

| **Parameter** | **Description** | **Remarks** |
| - | - | - |
| ProductId | The product ID to filter on. | Optional. Omit or use 0 for all owned products allowed by the token. A product lock applies automatically. |
| Start | The first UTC calendar date to include. | Optional, format yyyy-MM-dd. Supply with End, or omit both for the last 7 UTC calendar days including today. |
| End | The last UTC calendar date to include. | Optional, format yyyy-MM-dd. Supply with Start. The inclusive range must be ordered, contain at most 90 days, and not extend into the future. |
| CapacityMode | Whether to report excess or unused capacity. | Optional. Use exceeded (default) or below. Usage equal to the configured maximum is not a finding in either mode. |
| Granularity | The period represented by each result row. | Optional. Use day (default) or 30m. Daily rows describe the interval with the greatest excess or unused capacity. |
| 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** |
| - | - | - |
| Periods | A list of [capacity period](https://help.cryptolens.io/api-reference/generated/model/ReportResults.md#capacity-periods) objects. | Returned on success. Ordered by product ID, then period start. |
| Summary | A [capacity summary](https://help.cryptolens.io/api-reference/generated/model/ReportResults.md#capacity-summary) for the entire authorized date range. | Returned on success. Independent of Page and Limit. |
| Start | The resolved first UTC calendar date. | A string in yyyy-MM-dd format. Returned on success. |
| End | The resolved last UTC calendar date. | A string in yyyy-MM-dd format. Returned on success. |
| CapacityMode | The resolved capacity mode. | A string: exceeded or below. Returned on success. |
| Granularity | The resolved period size. | A string: day or 30m. Returned on success. |
| 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 product/period rows, including rows without findings or data. | 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 illustrates one product on 1 October 2026. Its greatest excess occurs at 12:00 UTC. The request example below uses the same product and date. IDs and values are illustrative.

```text theme={null}
{
  "start": "2026-10-01",
  "end": "2026-10-01",
  "capacityMode": "exceeded",
  "granularity": "day",
  "summary": {
    "monitoredProductCount": 1,
    "matchingProductCount": 1,
    "matchingLicenseCount": 1
  },
  "periods": [
    {
      "productId": 3349,
      "productName": "Example product",
      "periodStartUtc": 1790812800,
      "worstIntervalStartUtc": 1790856000,
      "capacityValue": 2,
      "trackedLicenseCount": 1,
      "licensesAtOrAboveLimit": 1,
      "hasData": true,
      "hasFinding": true,
      "isCurrent": false,
      "sourceUpdatedUtc": 1790857920
    }
  ],
  "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.
* The access token must allow the requested product. Key-locked tokens cannot access this product-level overview.
* In `exceeded` mode, **CapacityValue** sums only positive differences between floating machines and configured maximums. In `below` mode, it sums only negative differences. Underuse never cancels overuse.
* Daily rows use the worst interval's capacity value and license counts; ties select the earliest interval. **SourceUpdatedUtc** is the latest contributing source update for the day.
* Rows include periods without findings and periods without data. When **HasData** is false, numeric zeros do not mean observed zero usage, and **WorstIntervalStartUtc** is null. Future intervals within today are omitted.
* The summary contains **MonitoredProductCount**, **MatchingProductCount**, and distinct **MatchingLicenseCount** across the full authorized date range before pagination.
* Floating reports read asynchronously maintained state. Historical intervals use the latest state before the interval end; the current interval uses current tracked state. Values do not represent every instantaneous peak.
* **SourceUpdatedUtc** is a source-record timestamp, not a guarantee that every license is current. **GeneratedUtc** is the request time; separate requests may observe background updates.

#### Drill down

1. Call **GetFloatingCapacity** and find a period with **HasFinding=true**.
2. Pass its **ProductId** and **WorstIntervalStartUtc** to [Get Floating Capacity Licenses](https://help.cryptolens.io/api-reference/generated/GetFloatingCapacityLicenses.md) as **ProductId** and **IntervalStartUtc**, keeping the same **CapacityMode**. In the example, use product 3349 and interval 1790856000.
3. Pass a returned **ProductId** and **KeyId** to [Get Floating Capacity History](https://help.cryptolens.io/api-reference/generated/GetFloatingCapacityHistory.md) with the desired **Start** and **End**. The linked examples follow license 12345 in product 3349.

#### 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/GetFloatingCapacity \
  --data-urlencode "token=YOUR_USAGE_ANALYTICS_TOKEN" \
  --data-urlencode "ProductId=3349" \
  --data-urlencode "Start=2026-10-01" \
  --data-urlencode "End=2026-10-01" \
  --data-urlencode "CapacityMode=exceeded" \
  --data-urlencode "Granularity=day" \
  --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. |
| Supply both Start and End in yyyy-MM-dd format, or omit both. |
| The date range must be ordered, contain at most 90 days, and not extend into the future. |
| CapacityMode must be exceeded or below. |
| Granularity must be day or 30m. |

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


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