---
title: "Get a rental"
method: GET
path: "/v2/on-demand/rental"
tags: ["rentals"]
---

# Get a rental

`GET /v2/on-demand/rental`

## Request

- Base URL: `https://api.hyperbolic.ai`
- URL: `https://api.hyperbolic.ai/v2/on-demand/rental`
- Auth: HTTP bearer

Look up one rental by its ID, whether it is still running or has ended. Returns null when no rental with that ID belongs to the caller.

## Query parameters

- `rentalId` string, required: The rental's `rentalId`.

## Response `200`

Successful response

- union
  - ActiveRentalLookup: A rental lookup that found a running rental.
    - `state` 'active', required
    - `rental` RentalWithStatus, required: A GPU rental with its live status.
      - `rentalId` string, required
      - `name` string, nullable, required
      - `label` string, nullable, required
      - `rentalType` 'virtual-machine' | 'bare-metal', required
      - `region` 'us-central-1' | 'us-central-2' | 'eu-north-2' | 'eu-west-2' | 'eu-north-4' | 'eu-north-5' | 'us-east-1' | 'us-east-2' | 'ca-east-3' | 'eu-north-6' | 'eu-north-7' | 'eu-north-8' | 'eu-north-9' | 'ca-west-1' | 'ca-east-1' | 'us-central-3' | 'us-southeast-1' | 'me-central-1' | 'ca-east-2' | 'eu-west-1' | 'us-southeast-2' | 'jp-east-1' | 'us-southeast-3' | 'eu-west-5' | 'jp-east-2' | 'us-east-3' | 'uk-central-3' | 'uk-southeast-3' | 'eu-southwest-3' | 'eu-southwest-3-1' | 'eu-west-3' | 'eu-west-4' | 'private-cloud', required
      - `gpuType` 'h100' | 'h200' | 'b200' | 'rtx-6000-pro', required
      - `gpuCount` integer, required
      - `gpuFormFactor` 'sxm5' | 'sxm6' | 'pcie', required
      - `connectionType` 'infiniband' | 'ethernet', required
      - `ethernetVariant` 'normal' | 'rocev2', nullable, required
      - `nodes` RentalNode[], required
        - `cpuModel` string, required
        - `cpuCount` number, nullable, required
        - `vcpuCount` number, nullable, required
        - `gpuCount` number, required
        - `ramGb` number, required
        - `storageGb` number, required
      - `sshEndpoints` SshEndpoint[], required
        - `host` string, required
        - `port` number, required
        - `user` string, required
      - `networkInterfaces` NetworkInterface[], required
        - `publicIp` string, required
        - `privateIp` string, required
      - `portMappings` PortMapping[], required
        - `externalPort` number, required
        - `internalPort` number, required
      - `supportsPortForwarding` boolean, required
      - `exposedPorts` number[], required
      - `supportsCustomPorts` boolean, required
      - `supportsMultipleSshKeys` boolean, required
      - `supportsSshKeyUpdates` boolean, required
      - `attachedStorage` AttachedStorage[], required
        - `storageVolumeId` string, required
        - `label` string, required
        - `sizeInGb` integer, required
        - `virtualIp` string, required
        - `costPerHourCents` number, required
      - `supportsAttachedStorage` boolean, required
      - `monitoringEnabled` boolean, required
      - `convertToOnDemandOnExpiry` boolean, nullable, required
      - `terminationReason` string, nullable, required
      - `currentTerm` union, required
        - object
          - `effectiveAt` string, date-time, required
          - `termType` 'on-demand', required
          - `costPerHour` number, required
          - `reservedUntil` unknown, required
          - `reservationEndsAt` unknown, required
          - `termPeriodDays` unknown, required
          - `discountPercentage` unknown, required
          - `originalCostPerHour` unknown, required
        - object
          - `effectiveAt` string, date-time, required
          - `termType` 'reserved', required
          - `costPerHour` number, required
          - `reservedUntil` string, date-time, nullable, required
          - `reservationEndsAt` string, date-time, nullable, required
          - `termPeriodDays` number, required
          - `discountPercentage` number, required
          - `originalCostPerHour` number, required
        - object
          - `effectiveAt` string, date-time, required
          - `termType` 'private-cloud', required
          - `costPerHour` number, required
          - `reservedUntil` unknown, required
          - `reservationEndsAt` unknown, required
          - `termPeriodDays` unknown, required
          - `discountPercentage` unknown, required
          - `originalCostPerHour` unknown, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, nullable, required
      - `startedAt` string, date-time, nullable, required
      - `terminatedAt` string, date-time, nullable, required
      - `userId` string, required
      - `orgId` string, nullable, required
      - `createdBy` RentalCreator, required: The user who created a rental.
        - `id` string, required
        - `name` string, nullable, required
        - `email` string, required
        - `picture` string, nullable, required
      - `privateCluster` PrivateCluster, required: The topology of a dedicated private cluster.
        - `gpuModel` string, nullable, required
        - `location` string, nullable, required
        - `sshUser` string, required
        - `sshPort` number, nullable, required
        - `nodes` PrivateClusterNode[], required
          - `role` 'login' | 'head' | 'compute', required
          - `hostname` string, nullable, required
          - `publicIp` string, nullable, required
          - `privateIp` string, required
        - `handover` object, required
      - `managedCluster` ManagedClusterRef, required: The managed Kubernetes cluster a rental is a node pool of.
        - `name` string, required
        - `label` string, nullable, required
      - `status` 'Failed' | 'Pending' | 'Rebooting' | 'Running' | 'Terminating' | 'Terminated' | 'Unknown', required
      - `instances` RentalInstance[]
        - `instanceRef` string, required
        - `phase` string, required
        - `ssh` string, nullable, required
        - `internalIp` string, nullable, required
        - `supportsReboot` boolean, required
        - `actualResources` RentalInstanceResources: The hardware one node actually booted with, as its host reported it.
          - `vcpuCount` number, required
          - `ramGb` number, required
          - `gpuCount` number, required
          - `gpuMemoryGb` number
          - `gpuModel` string
          - `scratchDiskGb` number
          - `scratchDiskCount` number
          - `numaNodes` number
      - `monitoringOptOut` boolean, nullable, required: Whether the rental is opted out of Hyperbolic telemetry. Null where the rental can't opt out, or its setting couldn't be read.
  - TerminatedRentalLookup: A rental lookup that found a rental that has ended.
    - `state` 'terminated', required
    - `rental` HistoricalRental, required: A GPU rental that has ended, with its total cost.
      - `rentalId` string, required
      - `name` string, nullable, required
      - `label` string, nullable, required
      - `rentalType` 'virtual-machine' | 'bare-metal', required
      - `region` 'us-central-1' | 'us-central-2' | 'eu-north-2' | 'eu-west-2' | 'eu-north-4' | 'eu-north-5' | 'us-east-1' | 'us-east-2' | 'ca-east-3' | 'eu-north-6' | 'eu-north-7' | 'eu-north-8' | 'eu-north-9' | 'ca-west-1' | 'ca-east-1' | 'us-central-3' | 'us-southeast-1' | 'me-central-1' | 'ca-east-2' | 'eu-west-1' | 'us-southeast-2' | 'jp-east-1' | 'us-southeast-3' | 'eu-west-5' | 'jp-east-2' | 'us-east-3' | 'uk-central-3' | 'uk-southeast-3' | 'eu-southwest-3' | 'eu-southwest-3-1' | 'eu-west-3' | 'eu-west-4' | 'private-cloud', required
      - `gpuType` 'h100' | 'h200' | 'b200' | 'rtx-6000-pro', required
      - `gpuCount` integer, required
      - `gpuFormFactor` 'sxm5' | 'sxm6' | 'pcie', required
      - `connectionType` 'infiniband' | 'ethernet', required
      - `ethernetVariant` 'normal' | 'rocev2', nullable, required
      - `nodes` RentalNode[], required
        - `cpuModel` string, required
        - `cpuCount` number, nullable, required
        - `vcpuCount` number, nullable, required
        - `gpuCount` number, required
        - `ramGb` number, required
        - `storageGb` number, required
      - `sshEndpoints` SshEndpoint[], required
        - `host` string, required
        - `port` number, required
        - `user` string, required
      - `networkInterfaces` NetworkInterface[], required
        - `publicIp` string, required
        - `privateIp` string, required
      - `portMappings` PortMapping[], required
        - `externalPort` number, required
        - `internalPort` number, required
      - `supportsPortForwarding` boolean, required
      - `exposedPorts` number[], required
      - `supportsCustomPorts` boolean, required
      - `supportsMultipleSshKeys` boolean, required
      - `supportsSshKeyUpdates` boolean, required
      - `attachedStorage` AttachedStorage[], required
        - `storageVolumeId` string, required
        - `label` string, required
        - `sizeInGb` integer, required
        - `virtualIp` string, required
        - `costPerHourCents` number, required
      - `supportsAttachedStorage` boolean, required
      - `monitoringEnabled` boolean, required
      - `convertToOnDemandOnExpiry` boolean, nullable, required
      - `terminationReason` string, nullable, required
      - `currentTerm` union, required
        - object
          - `effectiveAt` string, date-time, required
          - `termType` 'on-demand', required
          - `costPerHour` number, required
          - `reservedUntil` unknown, required
          - `reservationEndsAt` unknown, required
          - `termPeriodDays` unknown, required
          - `discountPercentage` unknown, required
          - `originalCostPerHour` unknown, required
        - object
          - `effectiveAt` string, date-time, required
          - `termType` 'reserved', required
          - `costPerHour` number, required
          - `reservedUntil` string, date-time, nullable, required
          - `reservationEndsAt` string, date-time, nullable, required
          - `termPeriodDays` number, required
          - `discountPercentage` number, required
          - `originalCostPerHour` number, required
        - object
          - `effectiveAt` string, date-time, required
          - `termType` 'private-cloud', required
          - `costPerHour` number, required
          - `reservedUntil` unknown, required
          - `reservationEndsAt` unknown, required
          - `termPeriodDays` unknown, required
          - `discountPercentage` unknown, required
          - `originalCostPerHour` unknown, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, nullable, required
      - `startedAt` string, date-time, nullable, required
      - `terminatedAt` string, date-time, required
      - `userId` string, required
      - `orgId` string, nullable, required
      - `createdBy` RentalCreator, required: The user who created a rental.
        - `id` string, required
        - `name` string, nullable, required
        - `email` string, required
        - `picture` string, nullable, required
      - `privateCluster` PrivateCluster, required: The topology of a dedicated private cluster.
        - `gpuModel` string, nullable, required
        - `location` string, nullable, required
        - `sshUser` string, required
        - `sshPort` number, nullable, required
        - `nodes` PrivateClusterNode[], required
          - `role` 'login' | 'head' | 'compute', required
          - `hostname` string, nullable, required
          - `publicIp` string, nullable, required
          - `privateIp` string, required
        - `handover` object, required
      - `managedCluster` ManagedClusterRef, required: The managed Kubernetes cluster a rental is a node pool of.
        - `name` string, required
        - `label` string, nullable, required
      - `status` 'Terminated' | 'Failed', required
      - `totalCost` number, required

## Other responses

- `400`: Invalid input data
- `401`: Authorization not provided
- `403`: Insufficient access
- `404`: Not found
- `500`: Internal server error

## Changes

- **2026-10-31** `194666d30bfc`: 2 warning
  - added the new `jp-east-2` enum value to the `anyOf[subschema #1]/oneOf[#/components/schemas/ActiveRentalLookup]/rental/region` response property for the response status `200`
  - added the new `jp-east-2` enum value to the `anyOf[subschema #1]/oneOf[#/components/schemas/TerminatedRentalLookup]/rental/region` response property for the response status `200`
- **2026-10-27** `dbf29b4ec8ea`: 1 info
  - added the required property `anyOf[subschema #1]/oneOf[#/components/schemas/ActiveRentalLookup]/rental/monitoringOptOut` to the response with the `200` status
- **2026-10-26** `6d718ca26d2b`: 32 breaking, 32 info
  - the response property `anyOf[subschema #1]/oneOf[#/components/schemas/ActiveRentalLookup]/rental/convertToOnDemandOnExpiry` became nullable for the status `200`
  - the response property `anyOf[subschema #1]/oneOf[#/components/schemas/ActiveRentalLookup]/rental/createdBy/name` became nullable for the status `200`
  - the response property `anyOf[subschema #1]/oneOf[#/components/schemas/ActiveRentalLookup]/rental/createdBy/picture` became nullable for the status `200`
  - the response property `anyOf[subschema #1]/oneOf[#/components/schemas/ActiveRentalLookup]/rental/instances/items/internalIp` became nullable for the status `200`
  - …60 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/hyperbolic/apis/castle-api/changes/v2/on-demand/rental/get.md)

---

[API](https://skmtc.dev/hyperbolic/apis/castle-api.md) - [All operations](https://skmtc.dev/hyperbolic/apis/castle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hyperbolic/apis/castle-api/revisions/d4d4f25214b8?raw)