Skip to content
DigitalOcean Gradient™ AI Agentic Cloud SDK Docs
  • Auto
  • Light
  • Dark

Create

API Reference
GPU Droplets
Load Balancers
Create a New Load Balancer
post/v2/load_balancers

To create a new load balancer instance, send a POST request to /v2/load_balancers.

You can specify the Droplets that will sit behind the load balancer using one of two methods:

  • Set droplet_ids to a list of specific Droplet IDs.
  • Set tag to the name of a tag. All Droplets with this tag applied will be assigned to the load balancer. Additional Droplets will be automatically assigned as they are tagged.

These methods are mutually exclusive.

Body ParametersExpand Collapse
body: object { forwarding_rules, id, algorithm, 26 more } or object { forwarding_rules, id, algorithm, 26 more }
Accepts one of the following:
AssignDropletsByID = object { forwarding_rules, id, algorithm, 26 more }
forwarding_rules: array of ForwardingRule

An array of objects specifying the forwarding rules for a load balancer.

id: optional string

A unique ID that can be used to identify and reference a load balancer.

formatuuid
Deprecatedalgorithm: optional "round_robin" or "least_connections"

This field has been deprecated. You can no longer specify an algorithm for load balancers.

Accepts one of the following:
"round_robin"
"least_connections"
created_at: optional string

A time value given in ISO8601 combined date and time format that represents when the load balancer was created.

formatdate-time
disable_lets_encrypt_dns_records: optional boolean

A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.

domains: optional array of Domains

An array of objects specifying the domain configurations for a Global load balancer.

droplet_ids: optional array of number

An array containing the IDs of the Droplets assigned to the load balancer.

enable_backend_keepalive: optional boolean

A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.

enable_proxy_protocol: optional boolean

A boolean value indicating whether PROXY Protocol is in use.

firewall: optional LbFirewall

An object specifying allow and deny rules to control traffic to the load balancer.

glb_settings: optional GlbSettings

An object specifying forwarding configurations for a Global load balancer.

health_check: optional HealthCheck

An object specifying health check settings for the load balancer.

http_idle_timeout_seconds: optional number

An integer value which configures the idle timeout for HTTP requests to the target droplets.

minimum30
maximum600
ip: optional string

An attribute containing the public-facing IP address of the load balancer.

ipv6: optional string

An attribute containing the public-facing IPv6 address of the load balancer.

name: optional string

A human-readable name for a load balancer instance.

network: optional "EXTERNAL" or "INTERNAL"

A string indicating whether the load balancer should be external or internal. Internal load balancers have no public IPs and are only accessible to resources on the same VPC network. This property cannot be updated after creating the load balancer.

Accepts one of the following:
"EXTERNAL"
"INTERNAL"
network_stack: optional "IPV4" or "DUALSTACK"

A string indicating whether the load balancer will support IPv4 or both IPv4 and IPv6 networking. This property cannot be updated after creating the load balancer.

Accepts one of the following:
"IPV4"
"DUALSTACK"
project_id: optional string

The ID of the project that the load balancer is associated with. If no ID is provided at creation, the load balancer associates with the user's default project. If an invalid project ID is provided, the load balancer will not be created.

redirect_http_to_https: optional boolean

A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.

region: optional "ams1" or "ams2" or "ams3" or 12 more

The slug identifier for the region where the resource will initially be available.

Accepts one of the following:
"ams1"
"ams2"
"ams3"
"blr1"
"fra1"
"lon1"
"nyc1"
"nyc2"
"nyc3"
"sfo1"
"sfo2"
"sfo3"
"sgp1"
"tor1"
"syd1"
Deprecatedsize: optional "lb-small" or "lb-medium" or "lb-large"

This field has been replaced by the size_unit field for all regions except in AMS2, NYC2, and SFO1. Each available load balancer size now equates to the load balancer having a set number of nodes.

  • lb-small = 1 node
  • lb-medium = 3 nodes
  • lb-large = 6 nodes

You can resize load balancers after creation up to once per hour. You cannot resize a load balancer within the first hour of its creation.

Accepts one of the following:
"lb-small"
"lb-medium"
"lb-large"
size_unit: optional number

How many nodes the load balancer contains. Each additional node increases the load balancer's ability to manage more connections. Load balancers can be scaled up or down, and you can change the number of nodes after creation up to once per hour. This field is currently not available in the AMS2, NYC2, or SFO1 regions. Use the size field to scale load balancers that reside in these regions.

minimum1
maximum100
status: optional "new" or "active" or "errored"

A status string indicating the current state of the load balancer. This can be new, active, or errored.

Accepts one of the following:
"new"
"active"
"errored"
sticky_sessions: optional StickySessions

An object specifying sticky sessions settings for the load balancer.

target_load_balancer_ids: optional array of string

An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.

tls_cipher_policy: optional "DEFAULT" or "STRONG"

A string indicating the policy for the TLS cipher suites used by the load balancer. The possible values are DEFAULT or STRONG. The default value is DEFAULT.

Accepts one of the following:
"DEFAULT"
"STRONG"
type: optional "REGIONAL" or "REGIONAL_NETWORK" or "GLOBAL"

A string indicating whether the load balancer should be a standard regional HTTP load balancer, a regional network load balancer that routes traffic at the TCP/UDP transport layer, or a global load balancer.

Accepts one of the following:
"REGIONAL"
"REGIONAL_NETWORK"
"GLOBAL"
vpc_uuid: optional string

A string specifying the UUID of the VPC to which the load balancer is assigned.

formatuuid
AssignDropletsByTag = object { forwarding_rules, id, algorithm, 26 more }
forwarding_rules: array of ForwardingRule

An array of objects specifying the forwarding rules for a load balancer.

id: optional string

A unique ID that can be used to identify and reference a load balancer.

formatuuid
Deprecatedalgorithm: optional "round_robin" or "least_connections"

This field has been deprecated. You can no longer specify an algorithm for load balancers.

Accepts one of the following:
"round_robin"
"least_connections"
created_at: optional string

A time value given in ISO8601 combined date and time format that represents when the load balancer was created.

formatdate-time
disable_lets_encrypt_dns_records: optional boolean

A boolean value indicating whether to disable automatic DNS record creation for Let's Encrypt certificates that are added to the load balancer.

domains: optional array of Domains

An array of objects specifying the domain configurations for a Global load balancer.

enable_backend_keepalive: optional boolean

A boolean value indicating whether HTTP keepalive connections are maintained to target Droplets.

enable_proxy_protocol: optional boolean

A boolean value indicating whether PROXY Protocol is in use.

firewall: optional LbFirewall

An object specifying allow and deny rules to control traffic to the load balancer.

glb_settings: optional GlbSettings

An object specifying forwarding configurations for a Global load balancer.

health_check: optional HealthCheck

An object specifying health check settings for the load balancer.

http_idle_timeout_seconds: optional number

An integer value which configures the idle timeout for HTTP requests to the target droplets.

minimum30
maximum600
ip: optional string

An attribute containing the public-facing IP address of the load balancer.

ipv6: optional string

An attribute containing the public-facing IPv6 address of the load balancer.

name: optional string

A human-readable name for a load balancer instance.

network: optional "EXTERNAL" or "INTERNAL"

A string indicating whether the load balancer should be external or internal. Internal load balancers have no public IPs and are only accessible to resources on the same VPC network. This property cannot be updated after creating the load balancer.

Accepts one of the following:
"EXTERNAL"
"INTERNAL"
network_stack: optional "IPV4" or "DUALSTACK"

A string indicating whether the load balancer will support IPv4 or both IPv4 and IPv6 networking. This property cannot be updated after creating the load balancer.

Accepts one of the following:
"IPV4"
"DUALSTACK"
project_id: optional string

The ID of the project that the load balancer is associated with. If no ID is provided at creation, the load balancer associates with the user's default project. If an invalid project ID is provided, the load balancer will not be created.

redirect_http_to_https: optional boolean

A boolean value indicating whether HTTP requests to the load balancer on port 80 will be redirected to HTTPS on port 443.

region: optional "ams1" or "ams2" or "ams3" or 12 more

The slug identifier for the region where the resource will initially be available.

Accepts one of the following:
"ams1"
"ams2"
"ams3"
"blr1"
"fra1"
"lon1"
"nyc1"
"nyc2"
"nyc3"
"sfo1"
"sfo2"
"sfo3"
"sgp1"
"tor1"
"syd1"
Deprecatedsize: optional "lb-small" or "lb-medium" or "lb-large"

This field has been replaced by the size_unit field for all regions except in AMS2, NYC2, and SFO1. Each available load balancer size now equates to the load balancer having a set number of nodes.

  • lb-small = 1 node
  • lb-medium = 3 nodes
  • lb-large = 6 nodes

You can resize load balancers after creation up to once per hour. You cannot resize a load balancer within the first hour of its creation.

Accepts one of the following:
"lb-small"
"lb-medium"
"lb-large"
size_unit: optional number

How many nodes the load balancer contains. Each additional node increases the load balancer's ability to manage more connections. Load balancers can be scaled up or down, and you can change the number of nodes after creation up to once per hour. This field is currently not available in the AMS2, NYC2, or SFO1 regions. Use the size field to scale load balancers that reside in these regions.

minimum1
maximum100
status: optional "new" or "active" or "errored"

A status string indicating the current state of the load balancer. This can be new, active, or errored.

Accepts one of the following:
"new"
"active"
"errored"
sticky_sessions: optional StickySessions

An object specifying sticky sessions settings for the load balancer.

tag: optional string

The name of a Droplet tag corresponding to Droplets assigned to the load balancer.

target_load_balancer_ids: optional array of string

An array containing the UUIDs of the Regional load balancers to be used as target backends for a Global load balancer.

tls_cipher_policy: optional "DEFAULT" or "STRONG"

A string indicating the policy for the TLS cipher suites used by the load balancer. The possible values are DEFAULT or STRONG. The default value is DEFAULT.

Accepts one of the following:
"DEFAULT"
"STRONG"
type: optional "REGIONAL" or "REGIONAL_NETWORK" or "GLOBAL"

A string indicating whether the load balancer should be a standard regional HTTP load balancer, a regional network load balancer that routes traffic at the TCP/UDP transport layer, or a global load balancer.

Accepts one of the following:
"REGIONAL"
"REGIONAL_NETWORK"
"GLOBAL"
vpc_uuid: optional string

A string specifying the UUID of the VPC to which the load balancer is assigned.

formatuuid
ReturnsExpand Collapse
load_balancer: optional LoadBalancer
curl https://api.digitalocean.com/v2/load_balancers \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $DIGITALOCEAN_ACCESS_TOKEN" \
    -d '{
          "forwarding_rules": [
            {
              "entry_port": 443,
              "entry_protocol": "https",
              "target_port": 80,
              "target_protocol": "http"
            }
          ],
          "algorithm": "round_robin",
          "disable_lets_encrypt_dns_records": true,
          "droplet_ids": [
            3164444,
            3164445
          ],
          "enable_backend_keepalive": true,
          "enable_proxy_protocol": true,
          "http_idle_timeout_seconds": 90,
          "name": "example-lb-01",
          "network": "EXTERNAL",
          "network_stack": "IPV4",
          "project_id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
          "redirect_http_to_https": true,
          "region": "nyc3",
          "size": "lb-small",
          "size_unit": 3,
          "target_load_balancer_ids": [
            "7dbf91fe-cbdb-48dc-8290-c3a181554905",
            "996fa239-fac3-42a2-b9a1-9fa822268b7a"
          ],
          "tls_cipher_policy": "STRONG",
          "type": "REGIONAL",
          "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b"
        }'
{
  "load_balancer": {
    "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
    "name": "example-lb-01",
    "ip": "104.131.186.241",
    "size": "lb-small",
    "algorithm": "round_robin",
    "status": "new",
    "created_at": "2017-02-01T22:22:58Z",
    "forwarding_rules": [
      {
        "entry_protocol": "http",
        "entry_port": 80,
        "target_protocol": "http",
        "target_port": 80,
        "certificate_id": "",
        "tls_passthrough": false
      },
      {
        "entry_protocol": "https",
        "entry_port": 443,
        "target_protocol": "https",
        "target_port": 443,
        "certificate_id": "",
        "tls_passthrough": true
      }
    ],
    "health_check": {
      "protocol": "http",
      "port": 80,
      "path": "/",
      "check_interval_seconds": 10,
      "response_timeout_seconds": 5,
      "healthy_threshold": 5,
      "unhealthy_threshold": 3
    },
    "sticky_sessions": {
      "type": "none"
    },
    "region": {
      "name": "New York 3",
      "slug": "nyc3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent"
      ],
      "available": true
    },
    "tag": "",
    "droplet_ids": [
      3164444,
      3164445
    ],
    "redirect_http_to_https": false,
    "enable_proxy_protocol": false,
    "enable_backend_keepalive": false,
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b",
    "disable_lets_encrypt_dns_records": false,
    "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "http_idle_timeout_seconds": 60,
    "firewall": {
      "deny": [
        "cidr:1.2.0.0/16",
        "ip:2.3.4.5"
      ],
      "allow": [
        "ip:1.2.3.4",
        "cidr:2.3.4.0/24"
      ]
    }
  }
}
Returns Examples
{
  "load_balancer": {
    "id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
    "name": "example-lb-01",
    "ip": "104.131.186.241",
    "size": "lb-small",
    "algorithm": "round_robin",
    "status": "new",
    "created_at": "2017-02-01T22:22:58Z",
    "forwarding_rules": [
      {
        "entry_protocol": "http",
        "entry_port": 80,
        "target_protocol": "http",
        "target_port": 80,
        "certificate_id": "",
        "tls_passthrough": false
      },
      {
        "entry_protocol": "https",
        "entry_port": 443,
        "target_protocol": "https",
        "target_port": 443,
        "certificate_id": "",
        "tls_passthrough": true
      }
    ],
    "health_check": {
      "protocol": "http",
      "port": 80,
      "path": "/",
      "check_interval_seconds": 10,
      "response_timeout_seconds": 5,
      "healthy_threshold": 5,
      "unhealthy_threshold": 3
    },
    "sticky_sessions": {
      "type": "none"
    },
    "region": {
      "name": "New York 3",
      "slug": "nyc3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent"
      ],
      "available": true
    },
    "tag": "",
    "droplet_ids": [
      3164444,
      3164445
    ],
    "redirect_http_to_https": false,
    "enable_proxy_protocol": false,
    "enable_backend_keepalive": false,
    "vpc_uuid": "c33931f2-a26a-4e61-b85c-4e95a2ec431b",
    "disable_lets_encrypt_dns_records": false,
    "project_id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "http_idle_timeout_seconds": 60,
    "firewall": {
      "deny": [
        "cidr:1.2.0.0/16",
        "ip:2.3.4.5"
      ],
      "allow": [
        "ip:1.2.3.4",
        "cidr:2.3.4.0/24"
      ]
    }
  }
}