Skip to content

List or read pools

List accessible pools or read one pool's capacity and settings. Use parts to include only selected sections such as usage or snapshots.

Parameters

#
poolstring
Pool name or ID. Omit to list accessible pools.
partsstring[]
Section to include. Choose from usage, snapshots, plans and capacity. Use none for no additional sections. The default is all sections. MCP defaults to none.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
Accessible pools and requested details.
Show 8 attributesHide attributes
capacityobject
Capacity purchases and allocations for this account. May be omitted.
Show 4 attributesHide attributes
had_computerbooleanAlways present
Whether this account has ever created a Computer, including a deleted one.
purchasesobject[] | nullAlways present
Purchases held by the account, including payment-pending or lapsed purchases.
Show 1 attributeHide attributes
itemsobject
A capacity purchase and its payment status.
Show 15 attributesHide attributes
checkout_urlstring
Payment page for a pending purchase. May be omitted.
created_atstring (date-time)Always present
When the purchase was created.
idstringAlways present
Purchase ID used for changes or release.
kindstringAlways present
Billing model.
memory_bytesintegerAlways present
RAM included by this purchase, in bytes.
next_termsobject
Scheduled replacement terms. May be omitted.
Show 8 attributesHide attributes
amount_microsintegerAlways present
Price per billing period before discounts or a trial, in millionths of the currency.
currencystringAlways present
Currency of the price.
egress_gbintegerAlways present
Included monthly internet egress in decimal gigabytes.
modelstringAlways present
Hourly or monthly billing. Values: "hourly", "monthly".
planintegerAlways present
Plan number.
rate_cardobjectAlways present
Rates for usage beyond included allowances.
Show 2 attributesHide attributes
egress_micros_per_gbintegerAlways present
Internet egress overage price per decimal gigabyte, in millionths of a dollar.
hourly_minimum_minutesintegerAlways present
Minimum billed duration of an hourly purchase, in minutes.
storage_gbintegerAlways present
Included storage in decimal gigabytes.
unitsintegerAlways present
Number of capacity units purchased.
next_terms_atstring (date-time)
When replacement terms take effect. Monthly changes apply at renewal. May be omitted.
pays_microsinteger
Current price per hour or month according to kind, in millionths of a dollar. May be omitted.
planintegerAlways present
Purchased plan number.
poolsstring[] | nullAlways present
Pools that use capacity in this purchase's placement.
regionstring
Purchase's region. May be omitted.
statestringAlways present
active capacity is available. pending awaits its first monthly payment. out_of_funds, capped (stopped at the spending cap) and unpaid purchases have lapsed and contribute no capacity.
storage_bytesintegerAlways present
Storage included by this purchase, in bytes.
termsobject
Price and allowances agreed to for this purchase. May be omitted.
Show 8 attributesHide attributes
amount_microsintegerAlways present
Price per billing period before discounts or a trial, in millionths of the currency.
currencystringAlways present
Currency of the price.
egress_gbintegerAlways present
Included monthly internet egress in decimal gigabytes.
modelstringAlways present
Hourly or monthly billing. Values: "hourly", "monthly".
planintegerAlways present
Plan number.
rate_cardobjectAlways present
Rates for usage beyond included allowances.
Show 2 attributesHide attributes
egress_micros_per_gbintegerAlways present
Internet egress overage price per decimal gigabyte, in millionths of a dollar.
hourly_minimum_minutesintegerAlways present
Minimum billed duration of an hourly purchase, in minutes.
storage_gbintegerAlways present
Included storage in decimal gigabytes.
unitsintegerAlways present
Number of capacity units purchased.
vcpusintegerAlways present
vCPUs included by this purchase.
serversobject[] | nullAlways present
Capacity totals grouped by where the account's pools can use them.
Show 1 attributeHide attributes
itemsobject
Purchased and allocated capacity for pools in one placement.
Show 8 attributesHide attributes
memory_allocated_bytesintegerAlways present
Purchased RAM allocated to pools here, in bytes.
memory_bought_bytesintegerAlways present
RAM purchased here, in bytes.
poolsstring[] | nullAlways present
Pools using this placement's capacity.
regionstring
Region containing these pools. May be omitted.
storage_allocated_bytesintegerAlways present
Purchased storage allocated to pools here, in bytes.
storage_bought_bytesintegerAlways present
Storage purchased here, in bytes.
vcpus_allocatedintegerAlways present
Purchased vCPUs allocated to pools here.
vcpus_boughtintegerAlways present
vCPUs purchased here.
storageobject[] | nullAlways present
Storage included and used in each placement group.
Show 1 attributeHide attributes
itemsobject
The account's storage in one placement, including stopped pools.
Show 3 attributesHide attributes
included_bytesintegerAlways present
Storage included by the account's purchases here, in bytes.
regionstring
Region of this storage. May be omitted.
used_bytesintegerAlways present
Files and snapshots stored here as last measured, in bytes.
plansobject
Plans available for this account. May be omitted.
Show 2 attributesHide attributes
egress_micros_per_gbintegerAlways present
Internet egress overage price per decimal gigabyte, in millionths of a dollar.
plansobject[] | nullAlways present
Available plan definitions, including approval and current capacity availability.
Show 1 attributeHide attributes
itemsobject
A plan's capacity, prices and availability. Prices are millionths of a US dollar.
Show 13 attributesHide attributes
approvalboolean
Whether buying this plan requires approval. May be omitted.
approvedboolean
Whether this account has that approval. May be omitted.
egress_bytesintegerAlways present
Monthly internet egress added to the account's allowance, in bytes.
hourly_microsintegerAlways present
Hourly price for this account.
hourly_passes_monthly_hoursintegerAlways present
Hours held in a month beyond which hourly billing costs more than monthly.
memory_bytesintegerAlways present
Plan's RAM allocation, in bytes.
monthly_microsintegerAlways present
Monthly price for this account.
no_roomboolean
Whether all placements lack room for a new purchase. An existing purchase may still have room to grow. May be omitted.
planintegerAlways present
Plan number accepted by purchase commands.
public_portsintegerAlways present
Public port allowance for an account holding only this plan in a placement.
storage_bytesintegerAlways present
Plan's included storage, in bytes.
unitsintegerAlways present
Number of capacity units in this plan.
vcpusintegerAlways present
Plan's vCPU allocation.
poolobject
Additional detail when one pool was selected. May be omitted.
Show 6 attributesHide attributes
default_disk_bytesinteger
Default disk size for new Computers, in bytes. May be omitted.
default_domainstring
Default domain used to name new Computers. May be omitted.
default_vcpusinteger
Default per-Computer CPU setting for new Computers. May be omitted.
operationsobject[] | nullAlways present
Recent pool operations you started.
Show 1 attributeHide attributes
itemsobject
A recent pool operation in brief.
Show 3 attributesHide attributes
created_atstring (date-time)Always present
When the operation was accepted.
idstringAlways present
Operation ID to read for full progress.
kindstringAlways present
Pool change being tracked.
setup_scriptstring
Script for new Computers, visible to people allowed to create them. May be omitted.
sharesobject[]
Pool's shares, visible to its account's managers. May be omitted.
Show 1 attributeHide attributes
itemsobject
A pool share and the Computers its holders created through it.
Show 8 attributesHide attributes
commandsstring[]
Additional commands granted through the share. May be omitted.
computersintegerAlways present
Computers in the pool created by this share's holders.
emailstring
Recipient's email, including an address whose invitation has not yet been claimed. May be omitted.
organizationstring
Recipient organization, when shared with an organization. May be omitted.
poolstringAlways present
Pool name.
rolestringAlways present
Role granted through this share.
teamstring
Recipient team, when shared with a team. May be omitted.
user_idstring
Individual recipient's user ID. May be omitted.
poolsobject[] | nullAlways present
Selected pools and their reported state.
Show 1 attributeHide attributes
itemsobject
A pool's allocation, settings and reported state.
Show 28 attributesHide attributes
account_idstringAlways present
Account that owns the pool.
allowanceobjectAlways present
Resource allocation.
Show 3 attributesHide attributes
disk_allowance_bytesintegerAlways present
Pool's included storage for files and snapshots, in bytes.
memory_bytesintegerAlways present
Pool's guaranteed RAM allocation, in bytes.
vcpusintegerAlways present
Pool's vCPU allocation.
billingobject
Pool's payment state and any pending checkout. May be omitted.
Show 8 attributesHide attributes
checkout_urlstring
Checkout page while a monthly purchase waits for payment. May be omitted.
delete_atstring (date-time)
Scheduled deletion time, when one is set. May be omitted.
deletingboolean
Whether deletion is in progress. May be omitted.
out_of_funds_atstring (date-time)
When the pool's hourly capacity ran out of wallet funds. May be omitted.
paid_throughstring (date-time)
End of the paid subscription period. May be omitted.
providedboolean
True when Heaven provides this capacity without charging the account. May be omitted.
subscription_statusstring
Payment provider's subscription state. May be omitted.
unpaid_sincestring (date-time)
When the account's monthly renewal first went unpaid. May be omitted.
changeobject
A capacity change still being applied and any action needed. May be omitted.
Show 2 attributesHide attributes
messagestringAlways present
What is delaying the change and what you can do.
sincestring (date-time)Always present
When this pending change began.
computersobjectAlways present
How many of the pool's Computers you can see, by state. The Computer list with this pool in pool lists them.
Show 3 attributesHide attributes
statesmap<string, integer> | nullAlways present
How many are in each state; a state none is in is left out.
totalintegerAlways present
Computers you can see in the pool.
waiting_for_memoryintegerAlways present
Starting or restarting Computers that wait for memory to start.
cpu_coresnumber
Current measured vCPUs in use by the pool's Computers. May be omitted.
diskobject | nullAlways present
Latest storage measurements.
Show 1 attributeHide attributes
alternative-1object
A pool's reported storage usage.
Show 5 attributesHide attributes
allowance_bytesintegerAlways present
Included storage, in bytes.
files_bytesintegerAlways present
Storage attributed to Computer files beyond their base images, in bytes.
snapshot_bytesinteger
Storage attributed to snapshots, in bytes. May be omitted.
unknowninteger
Number of Computers whose disk usage could not be measured. May be omitted.
used_bytesintegerAlways present
Files and snapshots counted against the pool's storage, in bytes.
idstringAlways present
Pool's stable ID.
lifecyclestringAlways present
Pool's lifecycle state.
movesbooleanAlways present
Whether Computers can currently move between pools in this placement.
namestringAlways present
Pool name.
observed_atstring (date-time) | nullAlways present
When the pool was measured, or null before a measurement.
organizationstring
Owning organization's name, when applicable. May be omitted.
owner_emailstring
Personal account owner's email for a pool shared with you. May be omitted.
powerstringAlways present
Pool's saved power setting.
public_portsobject
Published-port usage and availability in the pool's applicable allowance. May be omitted.
Show 3 attributesHide attributes
limitintegerAlways present
Ports permitted within this allowance.
offeredbooleanAlways present
Whether an address is available for publishing ports. Required even with unused allowance.
usedintegerAlways present
Ports currently used within this allowance.
received_atstring (date-time) | nullAlways present
When Heaven received the observation, or null before one arrives.
received_bytesstring | nullAlways present
Recorded inbound bytes as a decimal string, or null without a measurement.
regionstring
Pool's region. May be omitted.
sent_bytesstring | nullAlways present
Recorded outbound bytes as a decimal string, or null without a measurement.
server_keystringAlways present
Opaque placement key. Matching keys permit moves between the pools.
shared_tostring[]
Your organizations receiving this pool share. May be omitted.
shared_withintegerAlways present
Number of people, organizations and teams sharing this pool.
shared_with_youboolean
Whether you access this pool through a share. May be omitted.
stalebooleanAlways present
Whether the observation is outdated.
static_addressstring
Static IPv4 address attached to this pool. May be omitted.
stop_lastbooleanAlways present
Whether this pool is marked to stop last when available capacity falls.
storagestring
Text summary of file and snapshot use against included storage. May be omitted.
snapshotsobject
Pool snapshots available in the selected scope. May be omitted.
Show 1 attributeHide attributes
pool_snapshotsobject[] | nullAlways present
Selected pool snapshots.
Show 1 attributeHide attributes
itemsobject
Disk snapshots captured from a pool. Sharing grants only disk-copy access.
Show 13 attributesHide attributes
computersintegerAlways present
Number of Computers represented by its parts.
created_atstring (date-time)Always present
When the grouped snapshot was created.
created_byobjectAlways present
Who requested the snapshot.
Show 2 attributesHide attributes
emailstring | nullAlways present
Their email address, or null when none is available.
user_idstringAlways present
Person's user ID.
expires_atstring (date-time) | nullAlways present
When it expires, or null if it has no expiry.
idstringAlways present
Pool snapshot's ID.
namestringAlways present
Its name within the pool.
notestringAlways present
Saved note about the snapshot.
partsobject[]
Individual saved disks, included when reading one snapshot. May be omitted.
Show 1 attributeHide attributes
itemsobject
A Computer's disk snapshot within a pool snapshot. Copying a part requires both Computer and snapshot identities.
Show 2 attributesHide attributes
computerobjectAlways present
Source Computer.
snapshotobjectAlways present
Its saved disk snapshot.
poolobjectAlways present
Source pool and its account.
Show 3 attributesHide attributes
idstringAlways present
Source pool's ID.
namestringAlways present
Source pool's name.
ownerobjectAlways present
Account that owns the source pool.
Show 4 attributesHide attributes
account_idstringAlways present
Account ID.
emailstring
Personal account owner's email. May be omitted.
kindstringAlways present
Whether the owner is an organization or a personal account.
namestring
Organization name. May be omitted.
regionstring
Region containing the source pool. May be omitted.
sharedbooleanAlways present
True when another account shared this snapshot with you.
shared_withobject[]
People this snapshot is shared with, visible to its account's members. May be omitted.
Show 1 attributeHide attributes
itemsobject
The person associated with a snapshot action or share.
Show 2 attributesHide attributes
emailstring | nullAlways present
Their email address, or null when none is available.
user_idstringAlways present
Person's user ID.
statestringAlways present
Grouped snapshot's recorded state.
unavailablestring[]
Requested parts that could not be read this time. May be omitted.
usageobject
Usage history for the selected pools, when requested. May be omitted.
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.
withheldstring[]
Requested parts your credential or role cannot read. May be omitted.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • API key permission: pool view.