API reference · Compute
Console, metadata and metrics
7 operations of the Ankra Cloud API: The console, the metadata service setting, server metrics and network transfer.
What the router's NAT gateway sent to the internet in the current period#
/v1/routers/{id}/transfer- Operation
get_router_transfer- Credentials
- API token, Portal session
- Requires
- Permission
read
Traffic that servers on the router's private networks send to the internet through its NAT gateway is metered on the gateway: outbound only, after address translation. Inbound traffic, traffic between private networks and traffic of a floating IP are not counted here.
While the router's dedicated uplink is active, the period is its current 30-day term: included_bytes is
the 50 TB the term includes (a TB is 10^12 bytes), billable_bytes is what was sent beyond it and
amount_cents is that at EUR 2 per TB. The allowance starts over with every term and what is left of it does
not carry over. Transfer beyond it is billed on the day it is sent, as usage of
resource_type: "nat_gateway_transfer" (hours 0) on the invoice of that day's month.
On the shared uplink the period is the current UTC calendar month. The router's total is recorded and nothing
is billed to the router: included_bytes, billable_bytes, price_per_terabyte_millicents and amount_cents
are 0. What each server sent through the gateway counts towards that server's own transfer allowance instead
(GET /v1/usage/network-transfer, nat_transmitted_bytes).
The figures follow the traffic by about a minute.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The router's NAT gateway transfer in the current period.application/json · RouterTransfer
| Field | Type | Description |
|---|---|---|
router_idrequired | string | |
uplinkrequired | string | dedicated while the router's dedicated uplink is active, shared otherwise.One of shared, dedicated |
period_startrequired | string (date-time) | The start of the current 30-day term of the dedicated uplink, or of the current UTC month on the shared uplink. |
period_endrequired | string (date-time) | |
transmitted_bytesrequired | integer (int64) | What the NAT gateway sent to the internet in the period. |
included_bytesrequired | integer (int64) | The transfer the term includes (50 TB of 10^12 bytes); 0 on the shared uplink. |
billable_bytesrequired | integer (int64) | The part of transmitted_bytes beyond included_bytes; 0 on the shared uplink. |
price_per_terabyte_millicentsrequired | integer (int64) | The price of a TB (10^12 bytes) beyond the included transfer, in thousandths of a cent; 0 on the shared uplink. |
amount_centsrequired | integer (int64) | What billable_bytes cost so far. |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/routers/<id>/transfer' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Type into the serial console#
/v1/servers/{id}/console/input- Operation
send_server_console_input- Credentials
- API token, Portal session
- Requires
- Permission
operate
At most 4 KiB (decoded) per request and 50 requests per second per account and server; beyond that the answer is 429 with Retry-After: 1. Each API token or signed-in user may also send at most 3000 a minute to this operation, whatever server it names; beyond that the answer is 429 with Retry-After in seconds. This operation has those limits of its own and is not counted against the credential's requests per minute, so it carries no X-RateLimit-* headers and typing never uses up what the rest of the API may be sent. The first input of each session_id is recorded in the audit log as server.console_session.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json · ConsoleInput
| Field | Type | Description |
|---|---|---|
session_idrequired | string (uuid) | One per open console; its first input is audited. |
datarequired | string (byte) | Base64 of at most 4096 bytes. |
Responses
204Sent to the server's serial port.
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429The operation's own limit is reached (its description says what the limit is), or the credential's 3000 requests a minute to operations with their own limit. The operation is not counted against the credential's requests per minute and sends no
X-RateLimit-*headers. - 503No capacity or address is free in the zone right now (
reason: capacity_unavailable, with availability wording indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/servers/<id>/console/input' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"session_id": "00000000-0000-0000-0000-000000000000",
"data": "string"
}'The interactive serial console as Server-Sent Events#
/v1/servers/{id}/console/stream- Operation
stream_server_console- Credentials
- API token, Portal session
- Requires
- Permission
operate - Note
- Reveals a credential or a live view; read-only support sessions are refused.
Starts with event: tail (base64 of the last 64 KiB of console output), then event: status with a ConsoleStatus, then one event: output (base64 of raw terminal bytes) per chunk the guest writes, and a : keepalive comment every 15 s. The stream ends after 30 minutes; EventSource clients reconnect.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The event stream.text/event-stream
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/servers/<id>/console/stream' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Whether the metadata service at 169.254.169.254 answers the server#
/v1/servers/{id}/metadata- Operation
get_server_metadata_setting- Credentials
- API token, Portal session
- Requires
- Permission
operate - Note
- Reveals a credential or a live view; read-only support sessions are refused.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The setting.application/json · MetadataSetting
| Field | Type | Description |
|---|---|---|
enabledrequired | boolean |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/servers/<id>/metadata' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Turn the metadata service on or off for the server#
/v1/servers/{id}/metadata- Operation
set_server_metadata_setting- Credentials
- API token, Portal session
- Requires
- Permission
operate
Applies within seconds, also to running servers.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json · MetadataSetting
| Field | Type | Description |
|---|---|---|
enabledrequired | boolean |
Responses
202Accepted; poll the operation (server.metadata).application/json
| Field | Type | Description |
|---|---|---|
enabledrequired | boolean | |
operationrequired | Operation | |
idrequired | string | |
kindrequired | string | One of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify |
server_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 409The resource's state does not allow this now.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X PUT 'https://cloud.ankra.app/v1/servers/<id>/metadata' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"enabled": false
}'Network and disk metrics of the server#
/v1/servers/{id}/metrics- Operation
get_server_metrics- Credentials
- API token, Portal session
- Requires
- Permission
read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
period | query | string |
Responses
200One point per step, oldest first, zero-filled; the last step is in progress.application/json · MetricsSeries
| Field | Type | Description |
|---|---|---|
periodrequired | string | One of 1h, 24h, 7d, 30d |
step_secondsrequired | integer | |
vcpusrequired | integer | The server's vCPUs, which cpu_percent is measured against. |
memory_total_bytesrequired | integer (int64) | The server's memory. |
pointsrequired | array of MetricsPoint | |
atrequired | string (date-time) | |
network_received_bytesrequired | integer (int64) | |
network_transmitted_bytesrequired | integer (int64) | |
disk_read_bytesrequired | integer (int64) | |
disk_written_bytesrequired | integer (int64) | |
disk_read_operationsrequired | integer (int64) | |
disk_write_operationsrequired | integer (int64) | |
cpu_percentrequired | number | null | Average share of the server's vCPUs that was busy in the step; null without a CPU sample. Includes the hypervisor's own threads, so a fully busy server can read slightly above 100. |
memory_used_bytesrequired | integer (int64) | null | Average memory the server's VM held in the step (guest memory it has touched plus the hypervisor's own); null without a memory sample. |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 404No such resource in the caller's account.
- 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/servers/<id>/metrics' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Outbound traffic per server in a month#
/v1/usage/network-transfer- Operation
get_network_transfer- Credentials
- API token, Portal session
- Requires
- Permission
billing.read
What a server sends to the internet is free up to 20 TB (10^12 bytes each) per server per calendar month and billed at €2 per TB beyond that (resource_type network_transfer): what its public interface sends, and what it sends through a router's shared NAT gateway (nat_transmitted_bytes, part of transmitted_bytes). A server behind a router whose dedicated uplink is active sends through that uplink's own allowance instead and nothing of it is counted here. Inbound and private-network traffic are free.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
month | query | string | The UTC month, YYYY-MM; the current one when omitted. |
Responses
200The month's network transfer.application/json · NetworkTransfer
| Field | Type | Description |
|---|---|---|
period_startrequired | string (date-time) | |
period_endrequired | string (date-time) | |
allowance_bytes_per_serverrequired | integer (int64) | |
price_per_terabyte_millicentsrequired | integer (int64) | |
total_received_bytesrequired | integer (int64) | |
total_transmitted_bytesrequired | integer (int64) | |
total_nat_transmitted_bytesrequired | integer (int64) | The part of total_transmitted_bytes the servers sent through a shared NAT gateway. |
total_billable_bytesrequired | integer (int64) | |
total_amount_centsrequired | integer (int64) | |
itemsrequired | array of object | |
server_idrequired | string | |
server_namerequired | string | |
received_bytesrequired | integer (int64) | |
transmitted_bytesrequired | integer (int64) | What the server sent to the internet, through its public interface and through a shared NAT gateway. |
nat_transmitted_bytesrequired | integer (int64) | The part of transmitted_bytes sent through a router's shared NAT gateway. |
billable_bytesrequired | integer (int64) | |
amount_centsrequired | integer (int64) | |
dailyrequired | array of object | |
daterequired | string (date) | |
received_bytesrequired | integer (int64) | |
transmitted_bytesrequired | integer (int64) |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/usage/network-transfer' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"