Capacity Finder API - CoreWeave Docs

This documentation describes CoreWeave’s (“CW”) Capacity Finder product (delivered via console or API). Data, content, images, links and other information generated by or accessed in relation to Capacity Finder constitutes CW’s property and confidential information (“Capacity Data”). Do not share such Capacity Data, including without limitation screenshots, exports, API responses, or related links outside your company.

To the extent your company’s agreement(s) with CW include confidentiality obligations, the Capacity Data is confidential thereunder; otherwise, you agree to keep it confidential and not disclose it without CW’s prior written consent. The Capacity Data is provided for general informational purposes only, without warranty, and to the maximum extent permitted by law, CW disclaims liability arising from its use, including any reliance on it for capacity planning, purchasing, or other business decisions. Any agreement(s) between your company and CW shall govern in the event of any conflict with this notice.

Capacity Finder helps you find Availability Zones where your GPU or CPU capacity request is likely to fit before you provision Nodes. It evaluates Spot capacity only. Spot Node Pools provide preemptible, pay-as-you-go compute with no long-term commitments. Use the Capacity Finder API to compare capacity programmatically. Send the instance types and Node counts you need, then use the ranked results to choose a Zone. To check capacity in the Cloud Console, see Capacity Finder. Capacity Finder returns guidance from cached capacity data. Results do not reserve Nodes or guarantee that provisioning succeeds.

Authentication

Use a CoreWeave API access token for your organization. Send the token in the Authorization header with the Bearer scheme. Capacity Finder requires an authenticated organization. It does not require an additional Capacity Finder-specific role or permission. Permissions to create and manage API access tokens are separate. See Manage API access tokens.

Request capacity availability

Send a JSON request to POST https://api.coreweave.com/v1beta1/capacity/availability:get with the following fields:

selections: One or more instance types, each paired with a requestedCount. Find the instance type identifier in the instance documentation. Use each instance type at most once. The Node count must be a positive whole number from 1 to 2147483647, encoded as a JSON integer, such as 8. Fractional Node counts are not supported.
capacityPlans: An array containing exactly one value, CAPACITY_PLAN_SPOT, the only supported capacity plan.
zones: Optional Availability Zone identifiers. Omit this field or send an empty array to evaluate all eligible Zones. Ineligible Zones are ignored.

Replace [API-ACCESS-TOKEN] with your token. Choose an instance type and Zone supported by the service for your request.

Request capacity availability

export COREWEAVE_API_TOKEN='[API-ACCESS-TOKEN]'

curl --request POST \
  'https://api.coreweave.com/v1beta1/capacity/availability:get' \
  --header "Authorization: Bearer ${COREWEAVE_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
  "selections": [
    {
      "instanceType": "gd-8xh100ib-i128",
      "requestedCount": 8
    }
  ],
  "capacityPlans": ["CAPACITY_PLAN_SPOT"],
  "zones": ["US-EAST-04A"]
}'

For the request and response schemas, see Get capacity availability.

Interpret the results

The response contains a flat results array. Each result identifies an Availability Zone, an instance type, a capacity plan, and a score. Results are sorted by descending score. Ordering for results with the same score is alphabetical by instance type and Zone. The score indicates how favorable capacity is for your requested Node count, based on cached data. Scores range from 0 to 0.95: 0 indicates no available capacity, and 0.95 is the highest availability score. Use higher scores to prioritize Zones where your request is more likely to fit. A score of 0.8 does not mean an 80% chance of successful provisioning, and even the highest score does not guarantee success. When the score is 0, the response omits the score field from that result. Treat a result without a score field as a score of 0. A selection without matching cached capacity contributes no results. A successful response can have no results. In that case, the response is {} with the results field omitted. Treat an absent results field as an empty result. You should not expect a result for every requested Zone and instance type. An unknown instance type fails the request instead of returning an empty result. The following response illustrates the result shape, not current capacity:

Example response

{
  "results": [
    {
      "zone": "US-EAST-04A",
      "score": 0.8,
      "instanceType": "gd-8xh100ib-i128",
      "capacityPlan": "CAPACITY_PLAN_SPOT"
    }
  ]
}

After you choose a Zone, create a Spot Node Pool to request capacity. Capacity can change between the query and provisioning.

​Authentication

​Request capacity availability

​Interpret the results

Authentication

Request capacity availability

Interpret the results