Fastly's Load Balancer allows you to create pools of origin servers that you dynamically manage using Dynamic Servers to distribute and direct incoming requests. To set up Dynamic Servers, you attach a pool to a service, then add versionless origin server that are stored separately from your VCL configuration. You can use the Fastly API to programmatically add, remove, and update pools and origin servers.

API Reference

Pool

A pool is responsible for balancing requests among a group of servers. In addition to balancing, pools can be configured to attempt retrying failed requests. Pools have a quorum setting that can be used to determine when the pool as a whole is considered up, in order to prevent problems following an outage as servers come back up.

Fields

field type description
id string

Alphanumeric string identifying this pool. Automatically generated.
service_id string

Alphanumeric string identifying a service. Automatically populated.
version integer

Current version of a service. Automatically populated.
name string

Name of pool. Required.
shield string

Selected POP to serve as a shield for servers. Optional. Defaults to null meaning no origin shielding if not set.
request_condition string

Condition which, if met, will select this pool during a request. Optional.
max_conn_default integer

Maximum number of connections. Optional. Defaults to 200 if not set.
connect_timeout integer

How long to wait for a timeout in milliseconds. Optional.
first_byte_timeout integer

How long to wait for the first byte in milliseconds. Optional.
quorum integer

Percentage of capacity (0-100) that needs to be operationally available for a pool to be considered up. Optional. Defaults to 75 if not set.
use_tls string

Whether or not to use TLS to reach any server in the pool. Optional. Defaults to "0".
tls_ca_cert string

CA certificate attached to origin. Optional.
tls_ciphers string

List of OpenSSL ciphers (see OpenSSL docs for details). Optional.
tls_client_key string

Client key attached to server. Optional.
tls_client_cert string

Client certificate attached to server. Optional.
tls_sni_hostname string

SNI hostname. Optional.
tls_check_cert string

Be strict on checking TLS certs. Optional.
tls_cert_hostname string

TLS cert hostname. Optional.
min_tls_version integer

Minimum allowed TLS version on connections to this server. Optional.
max_tls_version integer

Maximum allowed TLS version on connections to this server. Optional.
healthcheck string

Name of the healthcheck to use with this pool. Can be empty and could be reused across multiple backend and pools.
comment string

Optional.
type string

What type of load balance group to use. Values can be random, hash, client.
override_host string

The hostname to override the Host header. Optional. Defaults to null meaning no override of the Host header will occur. This setting can also be added to a Server definition. If the field is set on a Server definition it will override the Pool setting.

Actions

GET /service/service_id/version/version/pool

Lists all pools for a particular service and pool.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
version integer

Current version of a service.
Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/pool HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": "2Yd1WfiCBPENLloXfXmlO",
    "service_id": "62SNBYLi10xp1iixmsAcXy",
    "version": "1",
    "name": "my_pool",
    "shield": null,
    "override_host": null,
    "use_tls": "0",
    "type": "random",
    "request_condition": null,
    "max_conn_default": "200",
    "connect_timeout": "1000",
    "first_byte_timeout": "15000",
    "quorum": "75",
    "tls_ca_cert": null,
    "tls_ciphers": null,
    "tls_client_key": null,
    "tls_client_cert": null,
    "tls_sni_hostname": null,
    "tls_check_cert": "1",
    "tls_cert_hostname": null,
    "min_tls_version": null,
    "max_tls_version": null,
    "healthcheck": null,
    "comment": "",
    "created_at": "2016-06-20T03:55:06+00:00",
    "updated_at": "2016-06-20T03:55:06+00:00",
    "deleted_at": null
  }
]
GET /service/service_id/version/version/pool/pool_name

Gets a single pool for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
version integer

Current version of a service.
pool_name string

Name of the pool.
Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/pool/my_pool HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "2Yd1WfiCBPENLloXfXmlO",
  "service_id": "62SNBYLi10xp1iixmsAcXy",
  "version": "1",
  "name": "my_pool",
  "shield": null,
  "override_host": null,
  "use_tls": "0",
  "type": "random",
  "request_condition": null,
  "max_conn_default": "200",
  "connect_timeout": "1000",
  "first_byte_timeout": "15000",
  "quorum": "75",
  "tls_ca_cert": null,
  "tls_ciphers": null,
  "tls_client_key": null,
  "tls_client_cert": null,
  "tls_sni_hostname": null,
  "tls_check_cert": "1",
  "tls_cert_hostname": null,
  "min_tls_version": null,
  "max_tls_version": null,
  "healthcheck": null,
  "comment": "",
  "created_at": "2016-06-20T03:55:06+00:00",
  "updated_at": "2016-06-20T03:55:06+00:00",
  "deleted_at": null
}
POST /service/service_id/version/version/pool

Creates a pool for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
version integer

Development version of a service.
Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/pool HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Content-Type: application/x-www-form-urlencoded
name=my_pool
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "2Yd1WfiCBPENLloXfXmlO",
  "service_id": "62SNBYLi10xp1iixmsAcXy",
  "version": "1",
  "name": "my_pool",
  "shield": null,
  "override_host": null,
  "use_tls": "0",
  "type": "random",
  "request_condition": null,
  "max_conn_default": "200",
  "connect_timeout": "1000",
  "first_byte_timeout": "15000",
  "quorum": "75",
  "tls_ca_cert": null,
  "tls_ciphers": null,
  "tls_client_key": null,
  "tls_client_cert": null,
  "tls_sni_hostname": null,
  "tls_check_cert": "1",
  "tls_cert_hostname": null,
  "min_tls_version": null,
  "max_tls_version": null,
  "healthcheck": null,
  "comment": "",
  "created_at": "2016-06-20T03:55:06+00:00",
  "updated_at": "2016-06-20T03:55:06+00:00",
  "deleted_at": null
}
PUT /service/service_id/version/version/pool/pool_name

Updates a specific pool for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
version integer

Development version of a service.
pool_name string

Name of the pool.
Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/pool/my_pool HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Content-Type: application/x-www-form-urlencoded
max_conn_default=300
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "2Yd1WfiCBPENLloXfXmlO",
  "service_id": "62SNBYLi10xp1iixmsAcXy",
  "version": "1",
  "name": "my_pool",
  "shield": null,
  "override_host": null,
  "use_tls": "0",
  "type": "random",
  "request_condition": null,
  "max_conn_default": "300",
  "connect_timeout": "1000",
  "first_byte_timeout": "15000",
  "quorum": "75",
  "tls_ca_cert": null,
  "tls_ciphers": null,
  "tls_client_key": null,
  "tls_client_cert": null,
  "tls_sni_hostname": null,
  "tls_check_cert": "1",
  "tls_cert_hostname": null,
  "min_tls_version": null,
  "max_tls_version": null,
  "healthcheck": null,
  "comment": "",
  "created_at": "2016-06-20T03:55:06+00:00",
  "updated_at": "2016-06-20T03:55:06+00:00",
  "deleted_at": null
}
DELETE /service/service_id/version/version/pool/pool_name

Deletes a specific pool for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
version integer

Current version of a service.
pool_name string

Name of the pool.
Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/pool/my_pool HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Server

A server is an address (IP address or hostname) to which the Fastly Load Balancer service can forward requests. This service can define multiple servers and assign it to a pool. Fastly can then select any one of these servers based on a selection policy defined for the pool.

Fields

field type description
id string

Alphanumeric string identifying this server. Automatically generated.
service_id string

Alphanumeric string identifying a service. Automatically populated.
pool_id string

Alphanumeric string identifying a pool. Automatically populated.
weight string

Weight (1-100) used to load balance this server against others. Optional. Defaults to '100' if not set.
max_conn string

Maximum number of connections. If the value is '0', it inherits the value from pool's max_conn_default. Optional. Defaults to '0' if not set.
port string

Port number. Setting port 443 does not force TLS. Set use_tls in pool to force TLS. Optional. Defaults to '80' if not set.
address string

A hostname, IPv4, or IPv6 address for the server. Required.
comment string

Optional.
disabled boolean

Allows servers to be enabled and disabled in a pool.
override_host string

The hostname to override the Host header. Optional. Defaults to null meaning no override of the Host header if not set. This setting can also be added to a Pool definition. However, the server setting will override the Pool setting.
created_at string

Time-stamp (GMT) when the server was created.
deleted_at string

Time-stamp (GMT) when the server was deleted.
updated_at string

Time-stamp (GMT) when the server was updated.

Actions

GET /service/service_id/pool/pool_id/servers

Lists all servers for a particular service and pool.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
pool_id string

Alphanumeric string identifying a pool.
Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/pool/60OHK90EoxghKpGk4pGLyM/servers HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": "6kEuoknxiaDBCLiAjKqyXq",
    "service_id": "6k2He0IyVFUTO6RNO1BNDe",
    "pool_id": "6kAX81nQ1jsNWZGnXvFSKY",
    "weight": "100",
    "max_conn": "200",
    "port": "80",
    "override_host": null,
    "address": "example.com",
    "comment": "",
    "disabled": false,
    "created_at": "2016-06-20T08:20:36+00:00",
    "updated_at": "2016-06-20T08:20:36+00:00",
    "deleted_at": null
  }
]
GET /service/service_id/pool/pool_id/server/server_id

Gets a single server for a particular service and pool.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
pool_id string

Alphanumeric string identifying a pool.
server_id string

Alphanumeric string identifying this server.
Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/pool/60OHK90EoxghKpGk4pGLyM/server/6kEuoknxiaDBCLiAjKqyXq HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "6kEuoknxiaDBCLiAjKqyXq",
  "service_id": "6k2He0IyVFUTO6RNO1BNDe",
  "pool_id": "6kAX81nQ1jsNWZGnXvFSKY",
  "weight": "100",
  "max_conn": "200",
  "port": "80",
  "override_host": null,
  "address": "example.com",
  "comment": "",
  "disabled": false,
  "created_at": "2016-06-20T08:20:36+00:00",
  "updated_at": "2016-06-20T08:20:36+00:00",
  "deleted_at": null
}
POST /service/service_id/pool/pool_id/server

Creates a single server for a particular service and pool.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
pool_id string

Alphanumeric string identifying a pool.
Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/pool/60OHK90EoxghKpGk4pGLyM/server HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Content-Type: application/x-www-form-urlencoded
address=example.com
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "6kEuoknxiaDBCLiAjKqyXq",
  "service_id": "6k2He0IyVFUTO6RNO1BNDe",
  "pool_id": "6kAX81nQ1jsNWZGnXvFSKY",
  "weight": "100",
  "max_conn": "200",
  "port": "80",
  "override_host": null,
  "address": "example.com",
  "comment": "",
  "disabled": false,
  "created_at": "2016-06-20T08:20:36+00:00",
  "updated_at": "2016-06-20T08:20:36+00:00",
  "deleted_at": null
}
PUT /service/service_id/pool/pool_id/server/server_id

Updates a single server for a particular service and pool.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
pool_id string

Alphanumeric string identifying a pool.
server_id string

Alphanumeric string identifying this server.
Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/pool/60OHK90EoxghKpGk4pGLyM/server/6kEuoknxiaDBCLiAjKqyXq HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Content-Type: application/x-www-form-urlencoded
max_conn=300
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "6kEuoknxiaDBCLiAjKqyXq",
  "service_id": "6k2He0IyVFUTO6RNO1BNDe",
  "pool_id": "6kAX81nQ1jsNWZGnXvFSKY",
  "weight": "100",
  "max_conn": "300",
  "port": "80",
  "override_host": null,
  "address": "example.com",
  "comment": "",
  "disabled": false,
  "created_at": "2016-06-20T08:20:36+00:00",
  "updated_at": "2016-06-20T08:20:36+00:00",
  "deleted_at": null
}
DELETE /service/service_id/pool/pool_id/server/server_id

Deletes a single server for a particular service and pool.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
service_id string

Alphanumeric string identifying a service.
pool_id string

Alphanumeric string identifying a pool.
server_id string

Alphanumeric string identifying this server.
Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/pool/60OHK90EoxghKpGk4pGLyM/server/6kEuoknxiaDBCLiAjKqyXq HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}