Reclaim released GPU units from spot
Returns the named units to the reservation's exclusive use and terminates the spot workloads running on them, in one call. Everything evicted was bought at the spot tier, whose terms are exactly that the capacity owner can reclaim without notice. Pass dryRun to see what would be terminated without changing anything. Callable by a platform operator, the org that owns the node, or an org in the reservation's managingOrgIds while the reservation is active and inside its term.
Required permission
Requires the reservation.capacity permission. A caller without it gets 404. See Permissions for the roles and API key permissions that include it.
Command line
The orl CLI wraps this endpoint:
orl reservations unit reclaim <node-id> <id> --unit-ids <unit-ids>apiKeyAuthorizationBearer <token>OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).
nodeId*stringid*stringapplication/json- body
Reclaim takes units back off the spot market and terminates the spot workloads on them, so unlike release it can destroy someone's running VM: hence the dry run.
unitIds*array<string>reason?stringRecorded in the audit trail.
dryRun?booleanReport which spot workloads would be terminated, and change nothing: no terminations, and the capacity boundary stays where it is.
OK
application/json- response
Exclusive placement rights for a set of orgs over specific GPU units of one node, for a term. Scoped to units, not GPU counts, because units are the indivisible allocation primitive.
id*stringnodeId*stringreservedUnitIds*array<string>releasedUnitIds?array<string>The subset of reservedUnitIds currently on the spot market (double sell). Still this reservation's capacity, sellable to anyone at tier=spot only, and reclaimable at any time.
allowedOrgIds*array<string>The audience: orgs that may place workloads on the reserved units.
managingOrgIds?array<string>Orgs that may release these units to the market, reclaim them, and terminate the spot workloads on them, on the node owner's behalf, while the reservation is active and inside its term. Being in the audience does not confer this.
startsAt*stringendsAt?stringAbsent = open-ended until cancelled
status*stringneeds-review means the node's GPU topology changed under the reservation: it grants nothing (and withholds its units from everyone) until an operator re-affirms it.
"pending""active""expired""cancelled""needs-review"topologyGen?integerNode topology generation this reservation was written against
contractRef?stringreason?stringcreatedAt?stringupdatedAt?stringterminated?array<string>Reclaim only: spot VM ids terminated to free the reclaimed units.
skipped?array<string>Reclaim only: VM ids left running because they are not spot.
wouldTerminate?array<string>Reclaim dry run only: the spot VM ids this call would terminate.
wouldSkip?array<string>Reclaim dry run only: VM ids that would be left running.
curl -X POST 'https://api.openrelay.inc/v1/nodes/string/reservations/string/reclaim' \ -H 'Content-Type: application/json' \ -d '{ "unitIds": [ "string" ]}'{ "id": "string", "nodeId": "string", "reservedUnitIds": [ "string" ], "releasedUnitIds": [ "string" ], "allowedOrgIds": [ "string" ], "managingOrgIds": [ "string" ], "startsAt": "string", "endsAt": "string", "status": "pending", "topologyGen": 0, "contractRef": "string", "reason": "string", "createdAt": "string", "updatedAt": "string", "terminated": [ "string" ], "skipped": [ "string" ], "wouldTerminate": [ "string" ], "wouldSkip": [ "string" ]}Release GPU units to the spot market POST
Puts the named GPU units of a reservation on the spot market. They stay part of the reservation, and anyone may buy them, but only at tier=spot. This is the double-sell operation: spot-only sale is what makes them terminable by the capacity owner at any time. An ordinary community or verified request will never be placed on them, so released capacity can always be reclaimed. Callable by a platform operator, the org that owns the node, or an org in the reservation's managingOrgIds while the reservation is active and inside its term.
List GPU capacity reserved to this org GET
Returns the GPU reservations this organization is in the audience of or manages, with node ids, reserved units and terms. Expired and cancelled ones are left out; pending and needs-review reservations are included. With reservations not enabled for the org, the list is empty.