Parameters
#poolstring
Pool name or ID. Omit for all accessible pools.
rangestring
History period: 24h (default), 7d or 30d.
resolutionstring
History interval: 1m, 5m or 1h. Overrides
points. With neither, 24h uses 5m; 7d and 30d use 1h.pointsstring
Target maximum number of points per series, from 1 to 1000. A series includes at least one point per day. MCP defaults to 24 points. An explicit
resolution overrides this target.organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.
Returns
#dataobjectAlways present
Usage history for the selected pools, with their allocations and combined totals.
Show 4 attributesHide attributes
poolsobject[] | nullAlways present
Each pool's usage history.
Show 1 attributeHide attributes
itemsobject
A pool's usage history and allocation.
Show 10 attributesHide attributes
busiestobject[] | nullAlways present
Up to five Computers ordered by highest average CPU use.
Show 1 attributeHide attributes
itemsobject
One Computer's average CPU use and peak memory use in a pool's busiest list.
Show 4 attributesHide attributes
computer_idstringAlways present
Computer ID.
cpu_vcpus_avgnumber | nullAlways present
Average vCPUs in use over the range.
memory_bytes_peaknumber | nullAlways present
Peak measured memory use in bytes.
namestring
Its name when available. May be omitted.
computersobject[]
Computers ordered by egress, with peak memory use. May be omitted.
Show 1 attributeHide attributes
itemsobject
One Computer's outbound traffic and peak memory use over the selected range.
Show 5 attributesHide attributes
computer_idstringAlways present
Computer ID.
egress_bytesintegerAlways present
Bytes sent directly to the internet.
front_door_bytesintegerAlways present
Bytes sent through Heaven's front doors to visitors.
memory_bytes_peaknumber | nullAlways present
Peak measured memory use in bytes, or null if unmeasured.
namestring
Computer's name when available. May be omitted.
idstringAlways present
Pool ID.
memory_bytesintegerAlways present
Pool's RAM allocation in bytes.
organizationstring
Owning organization's name, when applicable. May be omitted.
poolstringAlways present
Pool name.
seriesobject[]Always present
Time-ordered intervals using the summary's measure names and units. Unmeasured values are omitted.
Show 1 attributeHide attributes
itemsobject
Measurements for one interval. Unmeasured values are omitted.
storage_allowance_bytesintegerAlways present
Pool's included storage in bytes.
summaryobjectAlways present
Usage over the selected range.
Show 15 attributesHide attributes
cpu_vcpus_avgnumber | nullAlways present
Average vCPUs used by the pool's Computers over measured minutes.
cpu_vcpus_peaknumber | nullAlways present
Average vCPUs used during the busiest measured minute.
cpu_vcpus_peak_atstring (date-time)
Busiest CPU minute, included in the summary. May be omitted.
disk_used_bytes_peakinteger | nullAlways present
Highest combined file use measured during the interval, in bytes, excluding snapshots.
egress_bytesinteger
Bytes sent directly to the internet. May be omitted.
front_door_bytesinteger
Bytes sent to visitors through Heaven's front doors. May be omitted.
io_read_bytesinteger | nullAlways present
Bytes read from the Computers' disks.
io_write_bytesinteger | nullAlways present
Bytes written to the Computers' disks.
memory_bytes_avgnumber | nullAlways present
Average combined memory use in bytes over measured minutes.
memory_bytes_peaknumber | nullAlways present
Peak combined memory use during a measured minute, in bytes.
memory_bytes_peak_atstring (date-time)
Busiest memory minute, included in the summary. May be omitted.
net_rx_bytesinteger | nullAlways present
Bytes received by the pool's Computers.
net_tx_bytesinteger | nullAlways present
Bytes sent by the pool's Computers.
startstring (date-time)Always present
Interval's start.
storage_bytesinteger | nullAlways present
Latest file use on running Computers, in bytes, excluding stale readings and snapshots.
vcpusintegerAlways present
Pool's vCPU allocation.
rangestringAlways present
Selected history range.
resolution_secondsintegerAlways present
Duration of each interval in seconds.
totalsobjectAlways present
Usage summed across the listed pools at matching times.
Show 7 attributesHide attributes
cpuobjectAlways present
Combined CPU use, in vCPUs.
Show 6 attributesHide attributes
avgnumber | nullAlways present
Average over measured points.
nownumber
Latest measured value. May be omitted.
peaknumber | nullAlways present
Highest combined point.
peak_atstring (date-time) | nullAlways present
When that peak occurred.
pools_at_peakobject[] | nullAlways present
Pool contributions at the combined peak.
Show 1 attributeHide attributes
itemsobject
A pool's contribution to a combined usage peak.
Show 3 attributesHide attributes
idstringAlways present
Pool ID.
poolstringAlways present
Pool name.
valuenumberAlways present
Its contribution, in the enclosing measure's units.
totalnumber
Sum over the range, used for egress. May be omitted.
egressobjectAlways present
Combined direct internet and front-door egress, in bytes.
Show 6 attributesHide attributes
avgnumber | nullAlways present
Average over measured points.
nownumber
Latest measured value. May be omitted.
peaknumber | nullAlways present
Highest combined point.
peak_atstring (date-time) | nullAlways present
When that peak occurred.
pools_at_peakobject[] | nullAlways present
Pool contributions at the combined peak.
Show 1 attributeHide attributes
itemsobject
A pool's contribution to a combined usage peak.
Show 3 attributesHide attributes
idstringAlways present
Pool ID.
poolstringAlways present
Pool name.
valuenumberAlways present
Its contribution, in the enclosing measure's units.
totalnumber
Sum over the range, used for egress. May be omitted.
memoryobjectAlways present
Combined measured memory use, in bytes.
Show 6 attributesHide attributes
avgnumber | nullAlways present
Average over measured points.
nownumber
Latest measured value. May be omitted.
peaknumber | nullAlways present
Highest combined point.
peak_atstring (date-time) | nullAlways present
When that peak occurred.
pools_at_peakobject[] | nullAlways present
Pool contributions at the combined peak.
Show 1 attributeHide attributes
itemsobject
A pool's contribution to a combined usage peak.
Show 3 attributesHide attributes
idstringAlways present
Pool ID.
poolstringAlways present
Pool name.
valuenumberAlways present
Its contribution, in the enclosing measure's units.
totalnumber
Sum over the range, used for egress. May be omitted.
memory_bytesintegerAlways present
Their total RAM allocation in bytes.
storageobjectAlways present
Combined measured file use on running Computers, in bytes, excluding snapshots.
Show 6 attributesHide attributes
avgnumber | nullAlways present
Average over measured points.
nownumber
Latest measured value. May be omitted.
peaknumber | nullAlways present
Highest combined point.
peak_atstring (date-time) | nullAlways present
When that peak occurred.
pools_at_peakobject[] | nullAlways present
Pool contributions at the combined peak.
Show 1 attributeHide attributes
itemsobject
A pool's contribution to a combined usage peak.
Show 3 attributesHide attributes
idstringAlways present
Pool ID.
poolstringAlways present
Pool name.
valuenumberAlways present
Its contribution, in the enclosing measure's units.
totalnumber
Sum over the range, used for egress. May be omitted.
storage_allowance_bytesintegerAlways present
Their total included storage in bytes.
vcpusintegerAlways present
Listed pools' total vCPU allocation.
Errors
#| Code | Status | What happened |
|---|---|---|
| invalid | 400 | An input is missing or invalid. |
| unauthenticated | 401 | The credential is missing, invalid, expired or revoked. |
| denied | 403 | The caller lacks permission for this action. |
| not_found | 404 | The resource is absent or inaccessible to this caller. |
| conflict | 409 | The request conflicts with the current resource state or an earlier request. |
| over_capacity | 409 | The request exceeds a resource or credential allowance. |
| access_list_full | 409 | The change would exceed the access-list allowance. |
| rate_limited | 429 | The caller's request rate exceeds its limit. |
| busy | 429 | Too much work is in progress to accept this request. |
| unknown | 503 | The outcome is unconfirmed; a change may have happened. |
| unavailable | 503 | The service or requested feature is unavailable. |
Notes
#- API key permission:
pool usage.