Read the status of a CloudAccount
const url = 'https://example.com/apis/nodus.dev/v1/cloudaccounts/example/status';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/apis/nodus.dev/v1/cloudaccounts/example/statusParameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”The object’s name.
Responses
Section titled “ Responses ”OK
CloudAccount is a customer’s own cloud account. An AWS, GCP or Azure account is read-only observation: inventory, GPUs and spend. Once spec.execute allows it, an AWS account through its execute role, a GCP account through its execute service account, an Azure subscription through its execute resource group, a key cloud’s account with the customer’s key and a Kubernetes namespace with its ServiceAccount token also run the org’s work: Nodus creates and deletes only machines carrying its ownership label, within the stated credit (ADR-130). The object holds only the non-secret binding; the grant material and key are stored encrypted, owned by the account and never returned.
object
object
object
object
object
object
object
CloudAccountSpec is the binding to one cloud account.
object
AWSAccount is an AWS binding through a read-only IAM role.
object
AccountID is the 12-digit AWS account id, empty until the stack’s ReturnToNodus link brings it back.
Regions limits observation; empty means every enabled region.
RoleARN is the read-only role the CloudFormation stack created; onboarding fills it.
AzureAccount is an Azure subscription Nodus reaches as its multi-tenant app, which the customer’s tenant admits with a read-only role on the subscription; the subscription carries a tag naming this CloudAccount.
object
Regions limits the GPU quota read; empty means the regions Nodus offers Azure GPUs in.
SubscriptionID is the subscription id, a UUID.
TenantID is the Entra tenant (directory) id, a UUID.
CloudCredits is the credit the customer states for the account: what is left today and when it expires. Nodus counts it down by the spend it observes from that day on; a cloud that reports its own balance wins.
object
AmountUSD is the credit left on the day it is stated.
ExpireTime is when the credit expires.
CloudExecute is the customer’s grant to run work in their own account and the credit Nodus may spend there. The cloud bills that spend to the customer; it never enters Nodus billing.
object
BurstToMarket says whether work that does not fit the account may run on other capacity. Default Allow.
CreditLimitUSD is the most cloud spend Nodus may cause in the account per period, estimated from list prices and running time; work stops placing there before it would pass the limit.
MaxHourlyUSD bounds the summed hourly price of the machines running there at once. Default the credit limit.
Period is Monthly (each UTC calendar month) or Total. Default Monthly.
Priority orders the org’s accounts: work goes to priority 1 first, then 2, up to 100; an account without one comes after every numbered account. Accounts of one priority compete on expected cost.
GCPAccount is a GCP binding through a read-only grant.
object
Method is how the customer granted access; OAuth, the default, is the only method accepted.
ProjectIDs are the projects Nodus observes. Empty starts Google consent before project selection.
WorkloadIdentityProvider names a workload identity provider (WorkloadIdentity, which is refused).
KubernetesAccount is a namespace of the customer’s own Kubernetes GPU cluster. Nodus runs each machine there as one pod asking for nvidia.com/gpu, with a ServiceAccount token whose Role covers only the namespace.
object
GPUs are the GPU types Nodus may ask the cluster for, each at the hourly rate the customer pays for one GPU, which meters execute.creditLimitUSD.
KubernetesGPU is one GPU type of the customer’s cluster.
object
HourlyUSD is the customer’s own price for one GPU for one hour, such as their contract rate.
NodeSelector is the node labels that pick this type’s nodes, such as nvidia.com/gpu.product; required when the account declares more than one type.
object
Type is the GPU model by its Nodus name, such as H100-SXM or A100-80G.
Namespace is the namespace every Nodus pod runs in. Immutable.
Region is the country the cluster runs in, as a two-letter key such as us or fi; it sets the region class of the account’s offerings. Immutable. Default us.
ScaleUpWaitMinutes is how long a pod no node has room for waits for the cluster’s autoscaler to add a node before Nodus runs the work elsewhere; 0 turns the wait off, for a fixed-size pool. Default 10, at most 20.
Observe lists the reads that run. Default [Inventory, GPUs, Spend].
Provider is AWS, GCP, Azure or a key cloud such as Lambda. Immutable.
CloudAccountSync sets the observation cadence.
object
Interval is from 15m to 24h. Default 1h.
CloudAccountStatus is the latest observation.
object
Conditions carries Verified and Synced.
object
CloudCreditStatus is the credit left in the customer’s cloud account. It is the cloud’s money, never Nodus credit, and an estimate between the cloud’s billing updates.
object
AsOfTime is when the credit was worked out.
ExpireTime is when the credit, or the first of several, expires.
Message says why the cloud’s own balance was not read, when it was not.
RemainingUSD is the credit left.
Source is Cloud, Stated or ExecuteLimit.
StatedTime is the UTC day the amount was stated; spend from that day on is subtracted (Stated).
StatedUSD is the stated amount the remaining credit counts down from (Stated).
CloudExecuteStatus is the work Nodus runs in the customer’s own account and the credit it has used there. The amounts are estimates from list prices and running time; the cloud bills the customer, never Nodus.
object
CreditRemainingUSD is the credit limit less the spend and the next five minutes of the machines running there; work moves to the next source before it reaches zero.
CreditUsedUSD is the cloud spend Nodus caused in the account this period.
InUse is true while Nodus machines run in the account.
KeyCheckTime is when Nodus last proved the account’s key or execute grant with the cloud, about every 15 minutes while the account runs work.
CloudExecuteError is one machine the customer’s cloud refused to create.
object
Message says what it means for the account.
Reason is CapacityUnavailable, CloudQuota (the account’s own quota refused it), ProviderRejected, Misconfigured, NotOffered, RegionMismatch, PriceDrift or another create outcome.
Time is when the create was refused.
Machines is the number of Nodus machines in the account now.
PeriodStartTime is when the current credit period began.
ExternalID is the AWS external id the role’s trust policy must name.
HandledRequests records the nodus.dev/verify-requested-at value the last requested sync answered.
object
CloudInventorySummary counts what the latest sync saw.
object
GPUQuota is how much GPU capacity the cloud lets the account run, per region and machine family; quotas of zero are left out.
CloudGPUQuota is one GPU quota of the account.
object
Family is the cloud’s name for the quota, such as “Running On-Demand P instances”, “NVIDIA_H100_GPUS” or “standardNCADSA100v4Family”.
Limit is the most the account may run at once.
Project is the GCP project, empty on AWS and Azure.
Region is the region the quota applies to, or “global” for every region together.
RequestURL opens the cloud console page where the customer asks for more.
Unit is GPUs or vCPUs.
Used is how much of it runs now, when the cloud reports it.
GPUs counts GPUs per accelerator model.
object
Instances is the number of instances observed.
Regions are the regions with instances.
RunningGPUs counts the GPUs of running instances per accelerator model; the rest of GPUs are on stopped or starting instances, which use no GPU hours.
object
LastSyncTime is when the latest sync finished.
MachinesMayBeRunning are the Nodus machines that may still run in the account while Nodus can no longer delete them (condition MachinesMayBeRunning); the customer deletes them in the cloud’s console.
CloudMachine is one machine in the customer’s own account, as the cloud’s console names it.
object
Location is the machine’s zone, or its region where the cloud names no zone.
Name is the instance name or id, or the Nodus label it carries while no create has answered.
Phase is Pending, Ready or Failed.
CloudSpendSummary is the month’s observed cloud spend; it never enters Nodus billing.
object
AsOfTime is when the spend was read.
MonthToDateUSD is observed month-to-date USD, possibly partial; empty when no USD was observed.
CloudSpendReport is the latest observation window, never a Nodus charge or a savings claim.
object
Basis explains adjustments and provisional billing data.
Currencies keeps different currencies separate; absent rows are unknown, not zero.
CloudSpendCurrency is one currency’s observed bill and optional projection.
object
ByRegion is the observed subtotal per billed region; charges the cloud bills to no region have an empty one.
CloudSpendRegion is one billed region’s observed subtotal in the currency report’s window.
object
CloudSpendService is one service’s observed subtotal in the currency report’s window.
object
ComputeServiceTotal is a service subtotal, including CPU and associated charges, never GPU-only spend.
CloudSpendCoverage describes past UTC days in the requested window; today’s partial day is excluded.
object
BilledThrough is the latest day explicitly reported non-estimated by the source, not invoice finality.
CloudSpendPoint leaves cost absent when no amount was observed. Unknown finality never means complete.
object
CloudSpendForecast extrapolates eligible observed days; it is neither a price guarantee nor a confidence band.
object
ComputeServiceTotal projects only the explicitly classified compute-service subtotal.
HistoryThrough is the latest UTC day used, exposing the export lag buffer.
Status is Ready, InsufficientHistory, BillingAdjustments or ProvisionalSource.
Total is the next HorizonDays at the recent daily average, not a month-end prediction.
MonthToDate sums returned amounts since the current month’s start; coverage may be partial.
ObservedTotal sums only returned amounts over the observation window.
FromDay is the first requested UTC day; ToDay is exclusive.
Source identifies the customer’s cloud billing source.
Example generated
{ "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "aws": { "accountId": "example", "regions": [ "example" ], "roleArn": "example" }, "azure": { "regions": [ "example" ], "subscriptionId": "example", "tenantId": "example" }, "credits": { "amountUSD": "example", "expireTime": "example" }, "execute": { "burstToMarket": "example", "creditLimitUSD": "example", "maxHourlyUSD": "example", "period": "example", "priority": 1 }, "gcp": { "method": "example", "projectIds": [ "example" ], "workloadIdentityProvider": "example" }, "kubernetes": { "gpus": [ { "hourlyUSD": "example", "nodeSelector": { "additionalProperty": "example" }, "type": "example" } ], "namespace": "example", "region": "example", "scaleUpWaitMinutes": 1 }, "observe": [ "example" ], "provider": "example", "sync": { "interval": "example" } }, "status": { "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "credits": { "asOfTime": "example", "expireTime": "example", "message": "example", "remainingUSD": "example", "source": "example", "statedTime": "example", "statedUSD": "example" }, "execute": { "creditRemainingUSD": "example", "creditUsedUSD": "example", "inUse": true, "keyCheckTime": "example", "lastError": { "message": "example", "reason": "example", "time": "example" }, "machines": 1, "periodStartTime": "example" }, "externalId": "example", "handledRequests": { "additionalProperty": "example" }, "inventory": { "gpuQuota": [ { "family": "example", "limit": 1, "project": "example", "region": "example", "requestUrl": "example", "unit": "example", "used": 1 } ], "gpus": { "additionalProperty": 1 }, "instances": 1, "regions": [ "example" ], "runningGPUs": { "additionalProperty": 1 } }, "lastSyncTime": "example", "machinesMayBeRunning": [ { "location": "example", "name": "example" } ], "phase": "example", "spend": { "asOfTime": "example", "report": { "basis": "example", "currencies": [ { "byRegion": [ { "cost": "example", "region": "example" } ], "byService": [ { "cost": "example", "service": "example" } ], "computeDescription": "example", "computeServiceTotal": "example", "coverage": { "billedThrough": "example", "completeDays": 1, "estimatedDays": 1, "missingDays": 1, "observedDays": 1 }, "currency": "example", "daily": [ { "complete": true, "cost": "example", "day": "example", "estimated": true } ], "forecast": { "computeDescription": "example", "computeServiceTotal": "example", "historyDays": 1, "historyThrough": "example", "horizonDays": 1, "method": "example", "status": "example", "total": "example" }, "monthToDate": "example", "observedTotal": "example" } ], "fromDay": "example", "source": "example", "toDay": "example" } } }}default
Section titled “ default ”An error: a metav1.Status whose reason is a registered code.
Status is the error body of every API response: a Kubernetes metav1.Status (so kubectl and client-go understand it) plus three top-level extensions that those clients ignore (ADR-028).
object
object
object
Docs is the URL of the code’s docs page.
Fix says what to do next, for example a CLI command or the field to change.
object
object
RequestID identifies the request in logs and support tickets.
Example generated
{ "apiVersion": "example", "code": 1, "details": { "causes": [ { "field": "example", "message": "example", "reason": "example" } ], "group": "example", "kind": "example", "name": "example", "retryAfterSeconds": 1, "uid": "example" }, "docs": "example", "fix": "example", "kind": "example", "message": "example", "metadata": { "continue": "example", "remainingItemCount": 1, "resourceVersion": "example", "selfLink": "example", "shardInfo": { "selector": "example" } }, "reason": "example", "requestId": "example", "status": "example"}