Documentation | Instances › List Network Ports

API Reference

Instances

instances

Methods

Assign Security Group ->

post/v1/instances/{project_id}/{region_id}/{instance_id}/addsecuritygroup

Assign the security group to the server. To assign multiple security groups to all ports, use the NULL value for the port_id field

Attach Interface -> { tasks }

post/v1/instances/{project_id}/{region_id}/{instance_id}/attach_interface

Attach interface to instance

Change Flavor -> { tasks }

post/v1/instances/{project_id}/{region_id}/{instance_id}/changeflavor

Change the flavor of the server instance

Check Quota For Instance Creation -> { baremetal_basic_count_limit, baremetal_basic_count_requested, baremetal_basic_count_usage, 126 more... }

post/v2/instances/{project_id}/{region_id}/check_limits

Check if regional quota is exceeded, if yes the number of additional quotas needed to create the specified instance will be calculated

Create Instance -> { tasks }

post/v2/instances/{project_id}/{region_id}

Create one or many instances or basic VMs. For Linux instances, use the 'username' and 'password' to create a new user. When only 'password' is provided, it is set as the password for the default user of the image. The 'user_data' is ignored when the 'password' is specified. Use the 'user_data' field to provide a cloud-init script in base64 to apply configurations to the instance. For Windows instances, the 'username' cannot be specified in the request. Use the 'password' field to set the password for the 'Admin' user on Windows. Use the 'user_data' field to provide a cloudbase-init script in base64 to create new users on Windows. The password of the Admin user cannot be updated via 'user_data'.

Delete Instance -> { tasks }

delete/v1/instances/{project_id}/{region_id}/{instance_id}

Delete instance

Detach Interface -> { tasks }

post/v1/instances/{project_id}/{region_id}/{instance_id}/detach_interface

Detach interface from instance

Get Instance Console URL -> { remote_console }

get/v1/instances/{project_id}/{region_id}/{instance_id}/get_console

Get instance console URL

Get Instance Metrics -> { count, results }

post/v1/instances/{project_id}/{region_id}/{instance_id}/metrics

Get instance metrics, including cpu, memory, network and disk metrics

Deprecated Get Instance Naming Restrictions That Are Applied To Specified Project And Region -> { custom_name_allowed, name_templates_limited, allowed_bm_name_templates, 3 more... }

get/v1/instances/{project_id}/{region_id}/available_names

Deprecated. Get instance naming restrictions that are applied to specified project and region.

Get Instance Security Groups -> { count, results }

get/v1/instances/{project_id}/{region_id}/{instance_id}/securitygroups

List of server security groups

List Instances -> OffsetPage<{ addresses, flavor, instance_created, 20 more... }>

get/v1/instances/{project_id}/{region_id}

The date and time stamp format in changes-since or changes-before should be ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, 2015-08-27T09:49:58-05:00. Values must be urlencoded. If the time zone is omitted, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-since must be earlier than or equal to the value of the changes-before.

Parameters

project_id: number

region_id: number

available_floating: boolean

Optional

Only show instances which are able to handle floating address

changes-before: string

Optional

Filters the instances by a date and time stamp when the instances last changed. Those instances that changed before or equal to the specified date and time stamp are returned.

changes-since: string

Optional

Filters the instances by a date and time stamp when the instances last changed status.

exclude_secgroup: string

Optional

Exclude instances with specified security group name

flavor_id: string

Optional

Filter out instances by flavor_id. Flavor id must match exactly. Example: "g1-standard-1-2"

flavor_prefix: string

Optional

Filter out instances by flavor_prefix. Example: "g1-standard" or "g1-"

include_ai: boolean

Optional

Include AI instances. default False.

include_baremetal: boolean

Optional

Include bare metal servers.default False.

include_k8s: boolean

Optional

Include k8s instances. default True.

ip: string

Optional

An IPv4 address to filter results by. Regular expression allowed

limit: number

Optional

Limit the number of returned instances

metadata_kv: string

Optional

Filter by metadata key-value pairs. Must be a valid JSON string. curl -G --data-urlencode "metadata_kv={"key": "value"}" --url "http://localhost:1111/v1/instances/1/1"

metadata_v: string

Optional

Filter by metadata values. Must be a valid JSON string. curl -G --data-urlencode "metadata_v=["value", "sense"]" --url "http://localhost:1111/v1/instances/1/1"

Optional

Filter out instances by name. Use MySQL regular expression. Example: "^.est_...._[0-9]$". Also, any substring can be used and instances will be returned with names containing the substring. Example: "test".

offset: number

Optional

Offset value is used to exclude the first set of records from the result

only_isolated: boolean

Optional

Include only isolated instances. default False.

only_with_fixed_external_ip: boolean

Optional

Return bare metals only with external fixed IP addresses.

order_by: string

Optional

Order instances by transmitted fields and directions (name.asc).

profile_name: string

Optional

Filter result by profile name. Effective only with with_ddos set to true.

protection_status: string

Optional

Filter result by DDoS protection_status. if parameter is provided. Effective only with with_ddos set to true. (Active, Queued or Error)

status: string

Optional

Filters instances by a server status, as a string. Possible statuses are ACTIVE, ERROR, SHUTOFF, REBOOT, PAUSED, etc.

type_ddos_profile: string

Optional

Return bare metals either only with advanced or only basic DDoS protection. Effective only with with_ddos set to true. (advanced or basic)

uuid: string

Optional

Filter the server list result by the UUID of the server. Allowed UUID part

with_ddos: boolean

Optional

DDoS profile information will be included to Bare metal servers

with_interfaces_name: boolean

Optional

Include interfaces name

Response fields

(minimum: 0)

Number of objects

results: Array<{ addresses, flavor, instance_created, 20 more... }>

Objects

Request example

curl https://api.gcore.com/cloud/v1/instances/$PROJECT_ID/$REGION_ID \
    -H "APIKey: $CLOUD_API_API_KEY"

200Example

{
  "count": 1,
  "results": [
    {
      "addresses": {
        "foo": [
          {
            "addr": "10.0.0.17",
            "type": "fixed"
          }
        ]
      },
      "flavor": {
        "architecture": "x86_64",
        "disabled": false,
        "flavor_id": "g1-gpu-1-2-1",
        "flavor_name": "g1-gpu-1-2-1",
        "os_type": "linux",
        "ram": 2048,
        "vcpus": 1,
        "capacity": 1,
        "currency_code": "USD",
        "hardware_description": {
          "foo": "string"
        },
        "price_per_hour": 1,
        "price_per_month": 720,
        "price_status": "error"
      },
      "instance_created": "2023-11-29T10:56:49Z",
      "instance_id": "6c6aa80f-7836-4dc2-a2ae-125e248be476",
      "instance_name": "gcore-instance-1",
      "project_id": 111,
      "region": "Luxembourg",
      "region_id": 4,
      "status": "active",
      "vm_state": "active",
      "volumes": [
        {
          "id": "id",
          "delete_on_termination": true
        }
      ],
      "blackhole_ports": [
        {
          "AlarmEnd": "2019-12-27T18:11:19.117Z",
          "AlarmStart": "2019-12-27T18:11:19.117Z",
          "AlarmState": "ACK_REQ",
          "AlertDuration": "2 hours",
          "DestinationIP": "80.240.114.116",
          "ID": 0
        }
      ],
      "creator_task_id": "creator_task_id",
      "ddos_profile": {
        "id": 0,
        "profile_template": {
          "id": 0,
          "name": "ICMP port",
          "description": "description",
          "fields": [
            {
              "id": 0,
              "name": "name",
              "default": "default",
              "description": "description",
              "field_type": "int",
              "required": "false",
              "validation_schema": {}
            }
          ]
        },
        "fields": [
          {
            "id": 0,
            "default": {},
            "description": "description",
            "field_value": {},
            "name": "name",
            "base_field": 0,
            "field_name": "field_name",
            "field_type": "field_type",
            "required": true,
            "validation_schema": {},
            "value": "value"
          }
        ],
        "options": {
          "active": true,
          "bgp": true
        },
        "profile_template_description": "ARK server ports. Valid port values are in range 1000-65535",
        "protocols": [
          {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          }
        ],
        "site": "ED",
        "status": {
          "error_description": "",
          "status": "Updated"
        }
      },
      "fixed_ip_assignments": [
        {
          "external": true,
          "ip_address": "123.123.123.1",
          "subnet_id": "eaafdc3c-f48b-4eb4-826f-057dfc7d6476"
        }
      ],
      "instance_description": "Instance description",
      "instance_isolation": {
        "reason": "Suspicious activities"
      },
      "keypair_name": "keypair_name",
      "metadata": {
        "key": "value"
      },
      "metadata_detailed": [
        {
          "key": "cost-center",
          "read_only": false,
          "value": "Luxembourg"
        }
      ],
      "security_groups": [
        {
          "name": "some_name"
        }
      ],
      "task_id": "task_id",
      "task_state": "task_state"
    }
  ]
}

List Flavors -> { count, results }

get/v1/flavors/{project_id}/{region_id}

Retrieve a list of flavors. When the include_prices query parameter is specified, the list shows prices. A client in trial mode gets all price values as 0. If you get Pricing Error contact the support

List Network Interfaces -> { count, results }

get/v1/instances/{project_id}/{region_id}/{instance_id}/interfaces

List network interfaces attached to the instance

List Network Ports -> { count, results }

get/v1/instances/{project_id}/{region_id}/{instance_id}/ports

List network ports of instance

Parameters

project_id: number

region_id: number

instance_id: string

Response fields

Optional

Number of objects

results: Array<{ id, name, security_groups }>

Optional

Objects

Request example

curl https://api.gcore.com/cloud/v1/instances/$PROJECT_ID/$REGION_ID/$INSTANCE_ID/ports \
    -H "APIKey: $CLOUD_API_API_KEY"

200Example

{
  "count": 1,
  "results": [
    {
      "id": "ae74714c-c380-48b4-87f8-758d656cdad6",
      "name": "name",
      "security_groups": [
        {
          "name": "name1",
          "id": "4536dba1-93b1-492e-b3df-270b6b9f3650"
        },
        {
          "name": "name2",
          "id": "cee2ca1f-507a-4a31-b714-f6c1ffb4bdfa"
        }
      ]
    }
  ]
}

Perform A Specific Action On An Instance -> { tasks }

post/v2/instances/{project_id}/{region_id}/{instance_id}/action

The action can be one of: start, stop, reboot, powercycle, suspend or resume. Suspend and resume are not available for baremetal instances.

Deprecated Powercycle Instance -> { addresses, blackhole_ports, creator_task_id, 21 more... }

post/v1/instances/{project_id}/{region_id}/{instance_id}/powercycle

Powercycle (stop and start) the instance, aka hard reboot

Put Instance Into The Server Group -> { tasks }

post/v1/instances/{project_id}/{region_id}/{instance_id}/put_into_servergroup

Put instance into the server group

Deprecated Reboot Instance -> { addresses, blackhole_ports, creator_task_id, 21 more... }

post/v1/instances/{project_id}/{region_id}/{instance_id}/reboot

Deprecated. Reboot instance

Remove Instance From The Server Group -> { tasks }

post/v1/instances/{project_id}/{region_id}/{instance_id}/remove_from_servergroup

Remove instance from the server group

Rename Instance -> { addresses, blackhole_ports, creator_task_id, 21 more... }

patch/v1/instances/{project_id}/{region_id}/{instance_id}

Rename instance

Deprecated Resume Instance -> { addresses, blackhole_ports, creator_task_id, 21 more... }

post/v1/instances/{project_id}/{region_id}/{instance_id}/resume

Resume a suspended server to an active state.

Get Instance -> { addresses, blackhole_ports, creator_task_id, 21 more... }

get/v1/instances/{project_id}/{region_id}/{instance_id}

Get instance

Search For Instance In All Clients Of The Reseller -> { count, results }

get/v1/instances/search

Search for instance in all clients of the reseller

Deprecated Start Instance -> { addresses, blackhole_ports, creator_task_id, 21 more... }

post/v1/instances/{project_id}/{region_id}/{instance_id}/start

Power on the server. Required VM state: Shutoff, Stopped

Deprecated Stop Instance -> { addresses, blackhole_ports, creator_task_id, 21 more... }

post/v1/instances/{project_id}/{region_id}/{instance_id}/stop

Power off the server. Required VM state: Active, Shutoff, Rescued

Deprecated Suspend Instance -> { addresses, blackhole_ports, creator_task_id, 21 more... }

post/v1/instances/{project_id}/{region_id}/{instance_id}/suspend

When you suspend a server, its VM state is stored on disk, all memory is written to disk, and the virtual machine is stopped. Suspending a server is similar to placing a device in hibernation, and its occupied resource will not be freed but rather kept for when the server is resumed. Required VM state: Active, Shutoff

Un Assign Security Group ->

post/v1/instances/{project_id}/{region_id}/{instance_id}/delsecuritygroup

Un-assign the security group to the server. To un-assign multiple security groups to all ports, use the NULL value for the port_id field

Instances

App Templates

instances.app_templates

Methods

List Apptemplates -> { count, results }

get/v1/apptemplates/{project_id}/{region_id}

Retrieve marketplace application templates list. Application templates are used in instance creation API v2

Get Apptemplate -> { id, category, description, 14 more... }

get/v1/apptemplates/{project_id}/{region_id}/{apptemplate_id}

Get apptemplate

Instances

Available Flavors

instances.available_flavors

Methods

Get Flavors For Instance -> { count, results }

post/v1/instances/{project_id}/{region_id}/available_flavors

Get flavors available for a potential instance

Get Flavors To Resize Into -> { count, results }

get/v1/instances/{project_id}/{region_id}/{instance_id}/available_flavors

Get flavors available for the instance to resize into

Instances

Metadata

instances.metadata

Methods

Create Or Update Metadata ->

post/v1/instances/{project_id}/{region_id}/{instance_id}/metadata

Create or update one or more metadata items for an instance. If an item does not exist, it gets created in the server metadata. If an item already exists, it's value is overwritten

Delete Instance Metadata Item ->

delete/v1/instances/{project_id}/{region_id}/{instance_id}/metadata/{key}

Delete instance metadata item by key. This endpoint does not support special characters in keys. Use /v2/instances/.../metadata_item instead.

Get Instance Metadata Item -> { key, read_only, value }

get/v1/instances/{project_id}/{region_id}/{instance_id}/metadata/{key}

Get instance metadata item by key. This endpoint does not support special characters in keys. Use /v2/instances/.../metadata_item instead.

List Instance Metadata -> { count, results }

get/v1/instances/{project_id}/{region_id}/{instance_id}/metadata

Lists all metadata for an instance

Replace Metadata ->

put/v1/instances/{project_id}/{region_id}/{instance_id}/metadata

All existing metadata is deleted and replaced with the metadata from the request

Instances

Metadata Item

instances.metadata_item

Methods

Delete Instance Metadata Item By Key ->

delete/v2/instances/{project_id}/{region_id}/{instance_id}/metadata_item

Delete instance metadata item by key

Get Instance Metadata Item By Key -> { key, read_only, value }

get/v2/instances/{project_id}/{region_id}/{instance_id}/metadata_item

Get instance metadata item by key

Instances

Reseller Name Templates

instances.reseller_name_templates

Methods

Delete The Reseller S Name Templates Setting And Drop All Naming Restrictions On The Region ->

delete/v1/reseller_name_templates/{reseller_id}/{region_id}

Delete the reseller's name_templates setting and drop all naming restrictions on the region.

Get Naming Restrictions That Are Applied To Specified Project And Region -> { custom_name_allowed, name_templates_limited, allowed_bm_name_templates, 5 more... }

get/v1/reseller_name_templates/{project_id}/{region_id}/available_names

Get naming restrictions that are applied to specified project and region.

List Name Template Configs Of The Reseller -> { count, results }

get/v1/reseller_name_templates

List name template configs of the reseller.

Update Or Create Reseller Naming Configuration -> { allow_custom_name, allowed_bm_name_templates, allowed_bm_name_win_templates, 7 more... }

put/v1/reseller_name_templates

Update or create reseller naming configuration.