AnkraDocs
Console

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#

GET/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

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The router's NAT gateway transfer in the current period.application/json · RouterTransfer

200 response fields
FieldTypeDescription
router_idrequiredstring
uplinkrequiredstringdedicated while the router's dedicated uplink is active, shared otherwise.One of shared, dedicated
period_startrequiredstring (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_endrequiredstring (date-time)
transmitted_bytesrequiredinteger (int64)What the NAT gateway sent to the internet in the period.
included_bytesrequiredinteger (int64)The transfer the term includes (50 TB of 10^12 bytes); 0 on the shared uplink.
billable_bytesrequiredinteger (int64)The part of transmitted_bytes beyond included_bytes; 0 on the shared uplink.
price_per_terabyte_millicentsrequiredinteger (int64)The price of a TB (10^12 bytes) beyond the included transfer, in thousandths of a cent; 0 on the shared uplink.
amount_centsrequiredinteger (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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/routers/<id>/transfer' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Type into the serial console#

POST/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

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json · ConsoleInput

Request body fields
FieldTypeDescription
session_idrequiredstring (uuid)One per open console; its first input is audited.
datarequiredstring (byte)Base64 of at most 4096 bytes.

Responses

204Sent to the server's serial port.

  • 400The request is invalid; detail says 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_credentials on 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 in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
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#

GET/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

Parameters
NameInTypeDescription
idrequiredpathstring

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_credentials on 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

bash
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#

GET/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

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The setting.application/json · MetadataSetting

200 response fields
FieldTypeDescription
enabledrequiredboolean
  • 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_credentials on 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

bash
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#

PUT/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

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json · MetadataSetting

Request body fields
FieldTypeDescription
enabledrequiredboolean

Responses

202Accepted; poll the operation (server.metadata).application/json

202 response fields
FieldTypeDescription
enabledrequiredboolean
operationrequiredOperation
idrequiredstring
kindrequiredstringOne 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_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

GET/v1/servers/{id}/metrics
Operation
get_server_metrics
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
periodquerystring

Responses

200One point per step, oldest first, zero-filled; the last step is in progress.application/json · MetricsSeries

200 response fields
FieldTypeDescription
periodrequiredstringOne of 1h, 24h, 7d, 30d
step_secondsrequiredinteger
vcpusrequiredintegerThe server's vCPUs, which cpu_percent is measured against.
memory_total_bytesrequiredinteger (int64)The server's memory.
pointsrequiredarray of MetricsPoint
atrequiredstring (date-time)
network_received_bytesrequiredinteger (int64)
network_transmitted_bytesrequiredinteger (int64)
disk_read_bytesrequiredinteger (int64)
disk_written_bytesrequiredinteger (int64)
disk_read_operationsrequiredinteger (int64)
disk_write_operationsrequiredinteger (int64)
cpu_percentrequirednumber | nullAverage 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_bytesrequiredinteger (int64) | nullAverage 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; detail says 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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/servers/<id>/metrics' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Outbound traffic per server in a month#

GET/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

Parameters
NameInTypeDescription
monthquerystringThe UTC month, YYYY-MM; the current one when omitted.

Responses

200The month's network transfer.application/json · NetworkTransfer

200 response fields
FieldTypeDescription
period_startrequiredstring (date-time)
period_endrequiredstring (date-time)
allowance_bytes_per_serverrequiredinteger (int64)
price_per_terabyte_millicentsrequiredinteger (int64)
total_received_bytesrequiredinteger (int64)
total_transmitted_bytesrequiredinteger (int64)
total_nat_transmitted_bytesrequiredinteger (int64)The part of total_transmitted_bytes the servers sent through a shared NAT gateway.
total_billable_bytesrequiredinteger (int64)
total_amount_centsrequiredinteger (int64)
itemsrequiredarray of object
server_idrequiredstring
server_namerequiredstring
received_bytesrequiredinteger (int64)
transmitted_bytesrequiredinteger (int64)What the server sent to the internet, through its public interface and through a shared NAT gateway.
nat_transmitted_bytesrequiredinteger (int64)The part of transmitted_bytes sent through a router's shared NAT gateway.
billable_bytesrequiredinteger (int64)
amount_centsrequiredinteger (int64)
dailyrequiredarray of object
daterequiredstring (date)
received_bytesrequiredinteger (int64)
transmitted_bytesrequiredinteger (int64)
  • 400The request is invalid; detail says 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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/usage/network-transfer' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"