3. Accounts
An API user account and password is required to access the UpCloud API. The API user is associated with an UpCloud account. A user account may have multiple API users to be used in different client software. In order to use resources from the cloud, the account must have enough credits.
Main account can create subaccounts that have access only to a limited set of resources (servers and storages). A subaccount can have API access, GUI access or both. API access can be further controlled with IP access lists. A subaccount can only query and modify its own details.
Credits
Credits are used to pay for cloud resources such as servers, storages, network traffic and IP addresses. Credits are automatically deducted for used resources on an hourly basis. Should the user run out of credits, active resources will be disabled and reactivated after the credit balance returns to positive. Credits can be purchased from the UpCloud website.
Get account information
Returns information on the user's account and resource limits.
Request
Normal response for a non-trial account
{
"account": {
"credits": 9972.2324,
"username": "username",
"resource_limits": {
"cores": 200,
"detached_floating_ips": 10,
"memory": 1048576,
"network_peerings": 100,
"networks": 100,
"ntp_excess_gib": 20000,
"public_ipv4": 100,
"public_ipv6": 100,
"storage_hdd": 10240,
"storage_maxiops": 10240,
"storage_ssd": 10240
}
}
}
Resource limit variables
| Variable | Description |
|---|---|
| cores | Maximum number of CPU cores |
| detached_floating_ips | Maximum number of detached floating IP addresses |
| memory | Maximum amount of memory in MiB |
| network_peerings | Maximum number of network peerings |
| networks | Maximum number of networks |
| ntp_excess_gib | Network Transfer Pool excess transfer limit after which bandwidth caps are applied |
| public_ipv4 | Maximum number of IPv4 addresses |
| public_ipv6 | Maximum number of IPv6 addresses |
| storage_hdd | Maximum amount of HDD storage space in MiB |
| storage_maxiops | Maximum amount of MaxIOPS storage space in MiB |
| storage_ssd | Maximum amount of SSD storage space in MiB |
Normal response for a trial account
{
"account": {
"credits": 9972.2324,
"username": "username",
"trial_resource_limits": {
"trial_firewall_restrictions": 1,
"trial_period_length": 90,
"trial_server_max_cores": 1,
"trial_server_max_memory": 1024,
"trial_server_max_public_ipv4": 1,
"trial_server_max_public_ipv6": 1,
"trial_storage_max_size": 30,
"trial_storage_tier": "maxiops",
"trial_total_detached_floating_ips": 1,
"trial_total_networks": 1,
"trial_total_public_ipv4": 1,
"trial_total_public_ipv6": 1,
"trial_total_server_cores": 1,
"trial_total_server_memory": 1024,
"trial_total_servers": 1,
"trial_total_storage_size": 30,
"trial_total_storages": 1,
"user_detached_floating_ips": null,
"user_networks": null,
"user_public_ipv4": null,
"user_public_ipv6": null,
"user_server_cores": null,
"user_server_memory": null
}
}
}
Trial resource limit variables
| Variable | Description |
|---|---|
| trial_firewall_restrictions | If 1, firewall option is disabled |
| trial_period_length | Trial period length in hours |
| trial_server_max_cores | Maximum number of CPU cores per server |
| trial_server_max_memory | Maximum amount of memory in MiB per server |
| trial_server_max_public_ipv4 | Maximum number of public IPv4 addresses per server |
| trial_server_max_public_ipv6 | Maximum number of public IPv6 addresses per server |
| trial_storage_max_size | Maximum storage size in GiB |
| trial_storage_tier | Storage tier type |
| trial_total_detached_floating_ips | Maximum number of detached floating IP addresses |
| trial_total_networks | Maximum number of networks |
| trial_total_public_ipv4 | Maximum number of public IPv4 addresses |
| trial_total_public_ipv6 | Maximum number of public IPv6 addresses |
| trial_total_server_cores | Maximum number of CPU cores |
| trial_total_server_memory | Maximum amount of memory in GiB |
| trial_total_servers | Maximum number of servers |
| trial_total_storage_size | Maximum amount of storage in GiB |
| trial_total_storages | Maximum number of storage devices |
| user_detached_floating_ips | Number of detached floating IP addresses |
| user_networks | Number of networks in use |
| user_public_ipv4 | Number of public IPv4 addresses in use |
| user_public_ipv6 | Number of public IPv6 addresses in use |
| user_server_cores | Number of CPU cores in use |
| user_server_memory | Amount of memory in use MiB |
Get account list
It is also possible to filter shown accounts with label URL parameters, e.g.
?label=organisation or ?label=org%3Dit. URL parameter can be given multiple
times to add more filters (e.g. ?label=org%3Dit&label=developers), where
only accounts that match all labels are returned.
Label keys are matched case insensitively.
Account listing is only available to the main account.
Normal response
{
"accounts": {
"account": [
{
"labels": [],
"roles": {
"role": ["technical"]
},
"type": "mymain",
"username": "test"
},
{
"labels": [],
"roles": {
"role": ["technical"]
},
"type": "sub",
"username": "my_sub_account"
},
{
"labels": [
{
"key": "to_be_removed",
"value": "after 2022-31-12"
}
],
"roles": {
"role": []
},
"type": "sub",
"username": "my_temp_account"
},
{
"labels": [],
"roles": {
"role": ["billing"]
},
"type": "sub",
"username": "my_billing_account"
}
]
}
}
Get account details
Request
where username is the account on which we want the details of.
Normal response
{
"account" : {
"main_account" : "mymain",
"type" : "sub",
"username" : "my_sub_account",
"first_name" : "first",
"last_name" : "last",
"company" : "UpCloud Ltd",
"address" : "my address",
"postal_code" : "00130",
"city" : "Helsinki",
"state" : "",
"country" : "FIN",
"currency" : "EUR",
"language" : "fi",
"phone" : "+358.31245434",
"email" : "[email protected]",
"vat_number" : "FI24315605",
"timezone" : "UTC",
"campaigns" : {
"campaign" : []
},
"roles" : {
"role" : []
},
"allow_api" : "yes",
"allow_gui" : "no",
"enable_3rd_party_services" : "yes",
"network_access" : {
"network" : []
},
"server_access" : {
"server" : [
{
"storage" : "no",
"uuid" : "*"
}
]
},
"storage_access" : {
"storage" : [
"*"
]
},
"tag_access" : {
"tag" : []
},
"ip_filters" : {
"ip_filter" : []
},
"labels": []
}
}
Modify account details
Request
or
where username is the account which we want to modify.
{
"account": {
"first_name": "first",
"last_name": "last",
"company": "my company name",
"address": "my address",
"postal_code": "00130",
"city": "Helsinki",
"state": "",
"country": "FIN",
"currency": "EUR",
"language": "en",
"phone": "+358.31245434",
"email": "[email protected]",
"vat_number": "my vat number",
"timezone": "Europe/Helsinki",
"roles": {
"role": [
"billing",
"aux_billing",
"technical"
]
},
"allow_api": "yes",
"allow_gui": "no",
"enable_3rd_party_services": "yes",
"network_access": {
"network": []
},
"server_access": {
"server": [
{
"uuid": "*",
"storage": "no"
}
]
},
"storage_access": {
"storage": [
"*"
]
},
"tag_access": {
"tag": [
{
"name": "mytag",
"storage": "yes"
},
{
"name": "mytag2",
"storage": "no"
}
]
},
"ip_filters": {
"ip_filter": []
},
"labels": [
{
"key": "role",
"value": "staging"
}
]
}
}
Normal response
Add subaccount
Request
{
"sub_account": {
"first_name": "first",
"last_name": "last",
"company" : "my company name",
"address" : "my address",
"postal_code" : "00130",
"city" : "Helsinki",
"state": "",
"country" : "FIN",
"phone" : "+358.31245434",
"email": "[email protected]",
"vat_number": "my vat number",
"timezone": "Europe/Helsinki",
"username": "myusername",
"password": "mysecr3tPassword",
"currency" : "EUR",
"language": "en",
"roles": {
"role": ["technical", "billing", "aux_billing"]
},
"allow_gui": "no",
"allow_api": "yes",
"network_access": {
"network" : []
},
"server_access": {
"server": []
},
"storage_access": {
"storage": []
},
"tag_access": {
"tag": []
},
"ip_filters": {
"ip_filter": []
},
"labels": [
{
"key": "department",
"value": "it"
}
]
}
}
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| first_name | string, length 1..50 chars | yes for billing accounts | First name | |
| last_name | string, length 1..50 chars | yes for billing accounts | Last name | |
| company | string, length 1..100 chars | |||
| address | string, 1 or 2 lines, each length 1..100 chars | yes for billing accounts | Street address | |
| postal_code | string, length 1..100 chars | yes for billing accounts | Postal/zip code | |
| city | string, length 1..100 chars | yes for billing accounts | City | |
| state | string | yes for billing accounts if country is USA | U.S. state | |
| country | ISO 3166-1 alpha-3 code | yes for billing accounts | ISO 3166-1 three character country code | |
| currency | EUR/GBP/USD/SGD | yes | Currency | |
| language | fi/en | yes | Language | |
| phone | +countrycode.nationalpart | yes | Phone number in international format, country code and national part separated by a period | |
| valid e-mail address | yes | E-mail address | ||
| vat_number | valid VAT number | no | Valid VAT number in the contact's country | |
| timezone | valid time zone | yes | Time zone in Continent/Location format | |
| username | valid username, 4..64 characters | yes | Username | |
| password | string | no | Password | |
| roles | list of account role names | no | Roles for the account; billing, aux_billing, or technical. An account's role defines features they can access and which kinds of messages they will receive from UpCloud | |
| labels | list of wanted labels for the account | no | Labels describing the sub account, objects with both "key" and "value" defined | |
| allow_api | yes/no | yes | Whether the account is allowed to use the API | |
| allow_gui | yes/no | yes | Whether the account is allowed to access the UpCloud control panel | |
| enable_3rd_party_services | yes/no | yes | no | Whether 3rd party services are allowed in the account's context when logged in the UpCloud control panel. Consult the complete description in the control panel. |
| network | list, elements network UUIDs or * |
* |
no | UUIDs of networks the account is allowed to manage, * means all |
| server | list, elements have uuid and storage attributes | yes | UUIDs of servers the account is allowed to manage. Servers by element uuid are granted access to, uuid * means all, and storage attribute controls access to the servers' storage management (yes/no, default no) | |
| storage | list, elements storage UUIDs or * |
yes | UUIDs of storages the account is allowed to manage, or * for all |
|
| tag | list, elements have name, storage attributes | yes | Tag based server/storage access permissions. Tags by element name are granted access to, and their storages based on the storage attribute (yes/no, default no) | |
| ip_filter | list, elements IP address ranges | no | IP address restrictions on API access; if set, allowed only from the specified ranges. Ranges can be specified in CIDR format, ranges separated by a dash, or as single IP addresses |
Normal response
Delete subaccount
where username is the subaccount we want to delete.
Normal response
Get monthly billing summary
Returns billing summary. API user account must have permission to read billing details.
Request
Where yearmonth specifies the year and month in the form YYYY-MM, e.g. 2019-12
Normal response
Example request and response
{
"billing": {
"currency": "EUR",
"networks": {
"bandwidth": {
"total_amount": 52.136
},
"total_amount": 52.136
},
"managed_databases": {
"managed_database": {
"total_amount": 80.13127
},
"total_amount": 80.13127
},
"object_storages": {
"object_storage": {
"total_amount": 2.2253
},
"total_amount": 2.2253
},
"servers": {
"server": {
"total_amount": 28.05132
},
"total_amount": 28.05132
},
"storages": {
"storage": {
"total_amount": 3.6224
},
"total_amount": 3.6224
},
"total_amount": 166.16629
}
}
Response content description
| Variable | Description |
|---|---|
| currency | Currency code |
| networks | All network resources combined |
| servers | All server resources combined |
| storages | All storage resources combined |
| object_storages | All object storage resources combined |
| total_amount | Cumulative amount from the beginning of the month |
Get detailed monthly billing summary
Returns detailed billing summary. API user account must have permission to read billing details.
Request
Where yearmonth specifies the year and month in the form YYYY-MM, e.g. 2019-12
Normal response
Example request and response
{
"billing": {
"currency": "EUR",
"networks": {
"bandwidth": {
"resources": [
{
"amount": 52.136,
"bandwidth_out": 953344,
"bandwidth_type": "public_ipv4",
"hours": 0,
"resource_id": "00ce9363-9065-4c2a-9d66-3b0c762f556b"
}
],
"total_amount": 52.136
},
"total_amount": 52.136
},
"managed_databases": {
"managed_database": {
"resources": [
{
"amount": 15.83323,
"hours": 114,
"plan": "2x2xCPU-4GB-50GB",
"resource_id": "09de34f1-c87e-48f5-9c99-2e1152b953e1"
},
{
"amount": 33.29854,
"hours": 137,
"plan": "3x2xCPU-4GB-100GB",
"resource_id": "09f858ad-aa13-4ab1-98d4-2366b32c0027"
},
{
"amount": 30.9995,
"hours": 744,
"plan": "1x1xCPU-2GB-25GB",
"resource_id": "095d8803-d6e7-4b03-add1-3938a4a32345"
}
],
"total_amount": 80.13127
},
"total_amount": 80.13127
},
"object_storages": {
"object_storage": {
"resources": [
{
"amount": 2.2253,
"hours": 2,
"resource_id": "0692388b-0b4a-46e7-ac58-d31c9effed64",
"size": 500
}
],
"total_amount": 2.2253
},
"total_amount": 2.2253
},
"servers": {
"server": {
"resources": [
{
"amount": 7.66668,
"firewall": 2.8,
"hours": 553,
"plan": "1xCPU-1GB",
"resource_id": "008c1044-208e-4344-b03b-fc16e9e27a09"
},
{
"amount": 6.16032,
"hours": 552,
"plan": "1xCPU-1GB",
"resource_id": "001b9e08-362f-4004-8318-43d0e61358f6"
},
{
"amount": 14.22432,
"hours": 552,
"plan": "1xCPU-1GB",
"resource_id": "00ce9363-9065-4c2a-9d66-3b0c762f556b"
}
],
"total_amount": 28.05132
},
"total_amount": 28.05132
},
"storages": {
"storage": {
"resources": [
{
"amount": 3.4224,
"hours": 552,
"resource_id": "01af6d71-43d4-433c-8342-0c9bc4068dda",
"size": 20
}
],
"template": [
{
"amount": 0.1000,
"resource_id": "01bfe607-dbac-44a3-9143-313d9c285e59",
"size": 10
}
],
"backup": [
{
"amount": 0.1000,
"resource_id": "01bfe607-76ac-42a3-914a-237dcc285ab2",
"size": 10
}
],
"total_amount": 3.6224
},
"total_amount": 3.6224
},
"total_amount": 166.16629
}
}
Response content description
| Variable | Description |
|---|---|
| currency | Currency code |
| amount | Cumulative amount the resource costs from the beginning of the month |
| resource_id | Server UUID, storage UUID, or IP address |
| plan | Simple plan's server plan type |
| cores | Flexible plan's server cores |
| memory | Flexible plan's server memory in MB |
| size | Storage size in GB |
| bandwidth_out | Outgoing traffic in bytes |
| total_amount | Cumulative amount from the beginning of the month |
Get monthly resource billing summary
Returns resource billing summary. API user account must have permission to read billing details.
Request
Query parameters
Where yearmonth specifies the year and month in the form YYYY-MM, e.g. 2019-12
| Parameter | Description | Example value |
|---|---|---|
| resource_id | Server UUID, storage UUID, or IP address | 001a6e07-232e-5928-8318-4ad0e4135853 |
| yearmonth | Specifies the year and month in the form YYYY-MM | 2019-12 |
Normal response
Example request and response
{
"billing": {
"daily_sums": {
"2019-12-02": 3.33684,
"2019-12-03": 52.77344,
"2019-12-04": 1.07424,
"2019-12-05": 1.07424,
"2019-12-06": 1.07424,
"2019-12-07": 1.07424,
"2019-12-08": 1.07424,
"2019-12-09": 1.07424,
"2019-12-12": 3.22272,
"2019-12-13": 0.58188
},
"details": {
"hours": 792,
"plan": "1xCPU-1GB",
"resource_id": "00ce9363-9065-4c2a-9d66-3b0c762f556b",
"title": "My Glorious Server",
"type": "server",
"zone": "fi-hel1"
},
"total_amount": 66.36032
}
}
Response content description
| Variable | Description |
|---|---|
| type | Type of resource |
| currency | Currency code |
| zone | The zone the resource belongs to |
| hours | The amount of hours the resource is billed from the beginning of the month |
| daily_sums | Daily resource cost |
| total_amount | Cumulative amount from the beginning of the month |
Get network transfer statistics
Returns network transfer statistics. If output type is JSON, maximum window size is 31 days. If output type is CSV, there's no limit to window size. Output type can be changed by setting Accept header as application/json or text/csv.
Request
Query parameters
| Query parameter | Accepted values | Default value | Description | Required |
|---|---|---|---|---|
| from | Timestamp in RFC 3339 format | First start time timestamp (UTC) | yes | |
| to | Timestamp in RFC 3339 format | Last start time timestamp (UTC) | yes | |
| accumulate | hour / day | day | Data accumulation in hours or days | no |
Example request and response for fetching hourly statistics
GET /1.3/account/network_usage/?from=2020-09-30T22:00:00Z&to=2020-10-01T00:00:00Z&accumulate=hour HTTP/1.1
{
"stats": {
"stat": [
{
"accumulated_quota_bytes": 6352371508013,
"projected_monthly_quota_bytes": 6362243967561,
"quota_increase_bytes": 9872459548,
"sent_bytes": 1254,
"start_time": "2020-09-30T22:00:00Z",
"total_sent_bytes": 225149331390
},
{
"accumulated_quota_bytes": 6362243967561,
"projected_monthly_quota_bytes": 6362243967561,
"quota_increase_bytes": 9872459548,
"sent_bytes": 1254,
"start_time": "2020-09-30T23:00:00Z",
"total_sent_bytes": 225149332644
},
{
"accumulated_quota_bytes": 9872459548,
"projected_monthly_quota_bytes": 7345109903712,
"quota_increase_bytes": 9872459548,
"sent_bytes": 906,
"start_time": "2020-10-01T00:00:00Z",
"total_sent_bytes": 906
}
]
}
}
Response content description
| Variable | Description |
|---|---|
| accumulated_quota_bytes | Accumulated quota in bytes |
| projected_monthly_quota_bytes | Projected quota is an estimation of how much quota you will have at the end of the month |
| quota_increase_bytes | Hourly/daily quota incrementation |
| sent_bytes | Bytes sent in an hour/a day |
| start_time | Start time of the measurement (UTC) |
| total_sent_bytes | Bytes sent so far in a month |
Example response in CSV format
start time,sent bytes,total sent bytes,accumulated quota bytes,projected monthly quota bytes,quota increase
2020-09-30T22:00:00Z,1254,225149331390,6352371508013,6362243967561,9872459548
2020-09-30T23:00:00Z,1254,225149332644,6362243967561,6362243967561,9872459548
2020-10-01T00:00:00Z,906,906,9872459548,7345109903712,9872459548
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | INVALID_DATE | TO date is older than FROM date |
| 400 Bad Request | INVALID_TIME_WINDOW_SIZE | Days between FROM and TO can't be over 31 days, if using JSON output |
Get resource transfer statistics
Returns resource transfer statistics. If output type is JSON, maximum window size is 31 days. If output type is CSV, there's no limit to window size. Output type can be changed by setting Accept header as application/json or text/csv.
Request
GET /1.3/account/resource_network_usage/?from={from}&to={to}&accumulate={accumulate}&service={service}&zone={zone}&resource_id={resource_id} HTTP/1.1
Query parameters
| Query parameter | Accepted values | Default value | Description | Required |
|---|---|---|---|---|
| from | Timestamp in RFC 3339 format | Data start timestamp (UTC) | yes | |
| to | Timestamp in RFC 3339 format | Data end timestamp (UTC) | yes | |
| zone | Zone name | All zones | Get statistics from selected zone(s). nb. Can enter multiple zone parameters. |
no |
| accumulate | hour / day | day | Data accumulation in hours or days | no |
| resource_id | Valid UUID | Limits search results for given resource | no | |
| service | server_public / object_storage_public | All services | Limits search results for given services | no |
Example request and response for fetching daily resource statistics
GET /1.3/account/resource_network_usage/?from=2020-09-07T00:00:00Z&to=2020-09-09T23:59:59Z&accumulate=day&service=server_public&service=object_storage_public&zone=fi-hel1&zone=de-fra1&resource_id=00777436-a6f8-43af-9daf-89e8e6833a7a HTTP/1.1
JSON
{
"stats": {
"stat": [
{
"resource_id": "00777436-a6f8-43af-9daf-89e8e6833a7a",
"sent_bytes": 10094,
"service": "server_public",
"start_time": "2020-09-07T00:00:00Z",
"zone": "de-fra1"
},
{
"resource_id": "00777436-a6f8-43af-9daf-89e8e6833a7a",
"sent_bytes": 35174050,
"service": "server_public",
"start_time": "2020-09-08T00:00:00Z",
"zone": "de-fra1"
},
{
"resource_id": "00777436-a6f8-43af-9daf-89e8e6833a7a",
"sent_bytes": 32790622,
"service": "server_public",
"start_time": "2020-09-09T00:00:00Z",
"zone": "de-fra1"
}
]
}
}
Response content description
| Variable | Description |
|---|---|
| resource_id | Resource's UUID |
| sent_bytes | Total bytes sent |
| service | Service type |
| start_time | Start time of the measurement (UTC) |
| zone | Zone name |
Example response in CSV format
start time,sent bytes,service,resource id,zone
2020-09-07T00:00:00Z,10094,server_public,00777436-a6f8-43af-9daf-89e8e6833a7a,fi-hel1
2020-09-08T00:00:00Z,35174050,server_public,00777436-a6f8-43af-9daf-89e8e6833a7a,fi-hel1
2020-09-09T00:00:00Z,32790622,server_public,00777436-a6f8-43af-9daf-89e8e6833a7a,fi-hel1
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | INVALID_DATE | TO date is older than FROM date |
| 400 Bad Request | INVALID_TIME_WINDOW_SIZE | Days between FROM and TO can't be over 31 days, if using JSON output |
Get current network usage
Return latest network transfer pool usage report
Request
Example response
{
"stats": {
"current_network_usage": {
"accumulated_quota_bytes": 3546328504778,
"hourly_quota_increase_bytes": 10577635230,
"projected_monthly_quota_bytes": 7777382596778,
"total_sent_bytes": 13682943146,
"updated": "2020-10-15T07:00:00Z"
}
}
}
Response content description
| Variable | Description |
|---|---|
| accumulated_quota_bytes | Accumulated quota in bytes |
| projected_monthly_quota_bytes | Projected quota is an estimation of how much quota you will have at the end of the month |
| hourly_quota_increase_bytes | Hourly quota incrementation |
| total_sent_bytes | Bytes sent so far in an ongoing month |
| updated | Last update time of usage data (UTC) |