> For the complete documentation index, see [llms.txt](https://docs.i3d.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.i3d.net/compute/flexmetal/capacity-and-usage.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.