The account's Volumes (contracts/machines/volume-v1.json): disks in one region, each bound to at most one Machine of that region through the Machine's volumes. The overview covers what every operation shares: authentication, roles, errors, pagination, idempotency and If-Match.
Needs account.read, which owner, admin and member hold. A narrowed key may call it.
The account's Volumes (contracts/machines/volume-v1.json) from every region, by name, including those being deleted until their purge ends; unavailable_regions names the regions whose Volumes could not be read. An account holds at most quotas.volumes_per_account Volumes, so the list is not paged. Served whatever machines.open says; a narrowed key never reaches a Volume.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
Needs machines.write, which owner, admin and member hold. A narrowed key may not.
A Volume in region, created available, of size_gib (1 to 100, fixed for its life). size_gib may be left out (contracts/machines/volume-v1.json size): in a region whose new Volumes take the account's size, the Volume is then the account's current total (contracts/billing/account-unlocks-v1.json volumes), at most 100 GiB; elsewhere it is 10 GiB. An account that has never bought credit holds one Volume, in any region, of at most its total (contracts/billing/account-unlocks-v1.json volumes): a second create answers 402 payment_required, and a size past the total the same naming size_gib; Volumes it already holds past one keep working. A Machine of the same region binds it through its spec volumes. It needs machines.write, a region where Machines are offered to the account (422 region_not_offered otherwise) and the account's Volumes there (contracts/machines/volume-v1.json flag, the same 422 otherwise). An account whose credit is exhausted answers 402 payment_required and nothing is written. A name another live Volume of the account holds, in any region, answers 409 conflict, and so does a Volume past the account's quotas.volumes_per_account. for_machine names the Machine the Volume is made for, as the console's create form does for the disk it makes, which then deletes it by default when that Machine is deleted (contracts/machines/machine-v2.json delete_volume); a replay must name the same one. The answer is 201 with the new Volume, and 200 when the same Idempotency-Key replays it; the key reused for another request answers 409. Both carry Location, the Volume's URL. Billing counts the Volume's live bytes, never its size.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
yes
A value you choose for this one creation, 1 to 255 characters, such as a new UUID. Send a new one for each resource you create, and the same one only to retry that request after a timeout or a lost answer: the retry answers what the first request created, in its current state, and never creates a second. A key reused for a different database, stream or Machine answers 409. 1 to 255 characters.
Request body
application/json, required. Unknown fields are refused.
The fields below are the contract’s, with their types and limits; Things to know explains what each one does.
Field
Type
Required
Description
name
string
yes
1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
region
string
yes
Matches ^[a-z]{2}(-gov)?-[a-z]+-[0-9]+$.
size_gib
integer
no
1 to 100.
for_machine
string
no
1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
Response
Status
Answer
200
The Volume an earlier request with this Idempotency-Key created
The account’s balance is zero, so nothing new is created. Also, before an account has paid (contracts/billing/account-unlocks-v1.json): a request that makes a Machine port public on an account with neither a card nor bought credit (errors names ports), and a Volume create by an account that has never bought credit that already holds a Volume in any region (volumes.never_paid_max_count, one), or of a Volume larger than its total, volumes.never_paid_total_gib without a card and volumes.card_bound_total_gib with one (size_gib).
No
Add credit on Usage & billing, which lifts all of them. Or add a card there (adding one charges nothing) for a public port or a larger Volume; then send the request again. (more)
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.
No
Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
The region could not be reached or read, or it takes no new resource of this kind. Every answer carries Retry-After.
After Retry-After
Send the request again after Retry-After; if detail says the region takes no new resource of this kind, name another region. (more)
Retries
Send a new Idempotency-Key with each request and the same one when you send it again: a repeat answers what the first request did, and the key reused for a different request answers 409 (see Idempotency).
429 and 503 carry Retry-After: wait that many seconds, then send the same request again.
Needs account.read, which owner, admin and member hold. A narrowed key may call it.
A Volume of the account: the live one of the name, or else the latest being deleted. machine names the Machine it is bound to, live_bytes what the chunk-store meter bills and last_commit_at its last committed flush. writes_held is non-null while the Machine's writes to it are held until a copy catches up, with since when and why; a held write is never failed. A region this server cannot reach answers 503 region_unavailable when the Volume is in no region it read.
Parameters
Name
In
Type
Required
Description
name
path
string
yes
The Volume's name. 1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
Needs machines.write, which owner, admin and member hold. A narrowed key may not.
A Volume bound to a Machine answers 409 conflict: remove it from the Machine first (volumes: []). Otherwise the Volume enters deleting and is purged: its data key is destroyed first, then its objects and its ledger (contracts/machines/volume-v1.json deletion); its name is free at once. The answer is 202 with the Volume being deleted, and again for a Volume already deleting. There are no Volume snapshots or backups, so a deleted Volume cannot be recovered.
Parameters
Name
In
Type
Required
Description
name
path
string
yes
The Volume's name. 1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.
No
Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
GET /v1/volumes/{name}/metrics · CLI: tonbo volume metrics
Needs account.read, which owner, admin and member hold. A narrowed key may call it.
One Volume's metrics over a window ending with the current step, by the UTC hour or day: its guest I/O (read_bytes, write_bytes, read_ops, write_ops, trim_ops), counted as its daemon served its Machine's requests, 0 in a step with none, and stored_bytes, what its files held at the step's last sample (taken every 5 minutes, written when it changed), carried from the step before when the step has none and null before its first. Hours go back 8 days and days 92. The I/O updates about every 30 seconds while the Volume is attached and starts with the hour its recording went live. The Volume is the live one of the name, or else the latest being deleted. The latency series (read_latency_p50_ms, read_latency_p99_ms, write_latency_p50_ms, write_latency_p99_ms) are the median and 99th percentile time the Volume's daemon took to answer the guest's successful reads and writes, from a request's arrival to its reply, write holds included; the account's are read from every Volume's merged histograms, never an average of percentiles, and a step with no timed request is null. Display only, never billed: what a Volume is billed for is /usage. Takes the parameters of getVolumeMetrics; stored_bytes here also answers hourly.
Parameters
Name
In
Type
Required
Description
name
path
string
yes
The Volume's name. 1 to 40 characters. Matches ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$. Never "self".
series
query
string
no
The series to answer, comma-separated, of stored_bytes, read_bytes, write_bytes, read_ops, write_ops, trim_ops, read_latency_p50_ms, read_latency_p99_ms, write_latency_p50_ms and write_latency_p99_ms; every series when omitted. Matches ^(stored_bytes|read_bytes|write_bytes|read_ops|write_ops|trim_ops|read_latency_p50_ms|read_latency_p99_ms|write_latency_p50_ms|write_latency_p99_ms)(,(stored_bytes|read_bytes|write_bytes|read_ops|write_ops|trim_ops|read_latency_p50_ms|read_latency_p99_ms|write_latency_p50_ms|write_latency_p99_ms))*$.
window
query
one of "24h", "7d", "30d" or "90d"
no
24h, the last 24 UTC hours, hourly; or the last 7, 30 or 90 UTC days, today included, daily (7d also hourly with granularity=hour).
granularity
query
one of "hour" or "day"
no
hour or day: the step, with from and to (day when omitted), or with window=7d.
from
query
string
no
With to, instead of window, the window's first step, a UTC hour for granularity=hour or a UTC midnight (or a date) by the day.
to
query
string
no
With from, the step boundary the window ends at, exclusive, at most 8 days after from by the hour or 92 by the day, and the end of the current step at the latest.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)