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

GET /1.3/account

Normal response for a non-trial account

HTTP/1.0 200 OK
{
  "account": {
    "credits": 9972.2324,
    "username": "username",
    "resource_limits": {
      "cores": 200,
      "detached_floating_ips": 10,
      "memory": 1048576,
      "networks": 100,
      "public_ipv4": 100,
      "public_ipv6": 100,
      "storage_hdd": 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
networks Maximum number of networks
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_ssd Maximum amount of SSD storage space in MiB

Normal response for a trial account

HTTP/1.0 200 OK
{
  "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

GET /1.3/account/list

Normal response

HTTP/1.0 200 OK
{
  "accounts": {
    "account": [
      {
        "roles": {
          "role": ["technical"]
        },
        "type": "mymain",
        "username": "test"
      },
      {
        "roles": {
          "role": ["technical"]
        },
        "type": "sub",
        "username": "my_sub_account"
      },
      {
        "roles": {
          "role": ["billing"]
        },
        "type": "sub",
        "username": "my_billing_account"
      }
    ]
  }
}

Get account details

Request

GET /1.3/account/details/username

where username is the account on which we want the details of.

Normal response

HTTP/1.0 200 OK
{
   "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" : "USD",
      "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" : []
      }
   }
}

Modify account details

Request

PUT /1.3/account/details/username

or

PUT /1.3/account/sub/username

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": "USD",
    "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": []
    }
  }
}

Normal response

HTTP/1.0 204 OK

Add subaccount

Request

POST /1.3/account/sub
{
  "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" : "USD",
    "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": []
    }
  }
}

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
email 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 which kinds of messages they will receive from UpCloud
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

HTTP/1.0 204 OK

Delete subaccount

DELETE /1.3/account/sub/username

where username is the subaccount we want to delete.

Normal response

HTTP/1.0 204 No Content

Get monthly billing summary

Returns billing summary. API user account must have permission to read billing details.

Request

GET /1.3/account/billing_summary/YYYY-MM

Where YYYY is year and MM is month e.g. 2019-12

Normal response

HTTP/1.0 200 OK

Example request and response

GET /1.3/account/billing_summary/2019-12
{
  "billing": {
    "currency": "USD",
    "networks": {
      "bandwidth": {
        "total_amount": 52.136
      },
      "total_amount": 52.136
    },
    "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": 86.03502
  }
}

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

GET /1.3/account/billing_summary/YYYY-MM/detailed

Where YYYY is year and MM is month e.g. 2019-12

Normal response

HTTP/1.0 200 OK

Example request and response

GET /1.3/account/billing_summary/2019-12/detailed
{
  "billing": {
    "currency": "USD",
    "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
    },
    "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": 86.03502
  }
}

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

GET /1.3/account/resource_billing_summary/RESOURCE_ID/YYYY-MM

Query parameters

Parameter Description Example value
RESOURCE_ID Server UUID, storage UUID, or IP address 001a6e07-232e-5928-8318-4ad0e4135853
YYYY-MM Year and month 2019-12

Normal response

HTTP/1.0 200 OK

Example request and response

GET /1.3/account/resource_billing_summary/00ce9363-9065-4c2a-9d66-3b0c762f556b/2019-12
{
  "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

GET /1.3/account/network_usage/?from=<timestamp>&to=<timestamp>&accumulate=(day|hour)

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
{
  "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=<timestamp>&to=<timestamp>&accumulate=(day|hour)&zone=<zone name>&zone=<another zone name>

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) 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

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

GET /1.3/account/current_network_usage

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)