# Capacity and Usage

## Plans (real-time capacity)

The `/plans` endpoint allows you to browse all available FlexMetal instance types and their current capacity status per data center.\
This is useful when deciding where to deploy new servers or automating region selection based on availability.

Endpoint:\
GET [https://api.i3d.net/v3/flexMetal/plans](https://docs.i3d.net/api/api_flexmetal#get-v3-flexmetal-plans)

This endpoint returns a list of available FlexMetal plans along with their hardware configuration and availability in each location.

Example response:

```
[
    {
        "name": "bm7.std.8",
        "hardwareDetails": {
            "cpu": {
                "name": "Intel(R) Xeon(R) E-2278G CPU @ 3.40GHz",
                "baseClock": 3400,
                "cpuCount": 1,
                "cpuCores": 8,
                "totalCores": 8
            },
            "memory": {
                "type": "ddr4",
                "size": 32
            },
            "disks": [
                {
                    "type": "ssd",
                    "size": 960
                }
            ],
            "networkInterfaces": [
                {
                    "type": "1 Gbps",
                    "count": 2
                }
            ],
            "gpu": null
        },
        "locations": [
            {
                "name": "US: Ashburn - VA",
                "dcCode": "usqas1",
                "availability": "high"
            },
            {
                "name": "EU: Rotterdam",
                "dcCode": "nlrtm1",
                "availability": "high"
            },
            {
                "name": "JP: Tokyo",
                "dcCode": "jptyo1",
                "availability": "low"
            },
            {
                "name": "HK: Hong Kong",
                "dcCode": "hkhkg1",
                "availability": "unavailable"
            }
        ]
    }
]
```

Availability levels may be one of the following:

* `high`: ample capacity available
* `medium`: limited capacity remaining
* `low`: only a few units left
* `unavailable`: currently out of stock

{% hint style="info" %}
The `/plans` endpoint reflects real-time capacity and can be queried before server creation to ensure available stock in your preferred location or using a different instance type based on availability.
{% endhint %}

## Quota and Historical Usage

In addition to real-time capacity you can track your historical consumption and configured quotas.

### View Quota Usage

To check your configured quotas (both OnDemand and Commit) and current utilization:

Endpoint:\
GET [https://api.i3d.net/v3/flexMetal/quota/usage](https://docs.i3d.net/api/api_flexmetal#get-v3-flexmetal-quota-usage)

Example response:

```
{
    "instanceType": {
        "id": 129,
        "name": "bm7.std.8"
    },
    "quotaType": "onDemand",
    "contractId": "",
    "quota": 100,
    "usage": 0
},
{
    "instanceType": {
        "id": 129,
        "name": "bm7.std.8"
    },
    "quotaType": "commit",
    "contractId": "PO12345",
    "quota": 2,
    "usage": 0
}
```

{% hint style="info" %}
The **contractId** is only relevant on the commit quotas. There is no **contractId** for OnDemand.
{% endhint %}

### Retrieve Historical Usage

You can obtain detailed usage information for a given period, including total runtime and bandwidth consumption.

Endpoint:\
GET [https://api.i3d.net/v3/flexMetal/usage?startDate=2025-01-01\&endDate=2025-02-01](https://docs.i3d.net/api/api_flexmetal#get-v3-flexmetal-usage)

Example response:

```
"startedAt": "2025-01-08T00:00:00.000Z",
"endedAt": "2025-01-08T13:42:09.000Z",
"totalHours": 14,
"totalMinutes": 823,
"bandwidthIn": 31243322,
"bandwidthOut": 670853110,
"totalEgressBytes": 31243322,
```

Where:

* `totalHours`: total billable usage hours
* `totalEgressBytes`: total egress traffic in Bytes (billable)

## Summary

| Use Case                  | Endpoint     | Description                                            |
| ------------------------- | ------------ | ------------------------------------------------------ |
| Check real-time capacity  | /plans       | View live availability and hardware specs by location  |
| View quota configuration  | /quota/usage | Inspect OnDemand and commit quotas and current usage   |
| Retrieve historical usage | /usage       | Get detailed billing metrics for runtime and bandwidth |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.i3d.net/compute/flexmetal/capacity-and-usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.