Get a property

get https://{hostname}/config-gtm/v1/domains/{domainName}/properties/{propertyName}

Returns information for a specific GTM property.

Response

Response body

object

backupCName

string | null

required

Specifies a backupCName. If GTM declares that all of the servers configured for your property are down, and you configured a backupCName, then queries for the property return the backupCName. If a backupCName is set, don't set a backupIp.

backupIp

string | null

required

Specifies a backup IP. When GTM declares that all of the targets are down, it hands out the backupIP. The IP type coincides with the property's iPv6 setting. If a backupIp is set, do not set a backupCName.

balanceByDownloadScore

boolean

Indicates whether download score based load balancing is enabled. GTM estimates the load on your data centers based on how long they take to respond to GTM liveness tests. The advantage: you don't need to implement a load object. The disadvantage: it's a very crude measure of load, and usually highly nonlinear. As load increases, download times don't increase significantly, until there is too much load. When that happens, the download times skyrocket. This can easily cause erratic load balancing or load oscillations.

cname

string | null

Indicates the fully qualified name aliased to a particular property. The public name of the property.

comments

string | null

Provides information about the purpose of the property.

dynamicTTL

integer

required

30 to 3600

Indicates the TTL in seconds for records that might change dynamically based on liveness and load balancing such as A and AAAA records, and CNAMEs. The value ranges from 30 to 3600 and can change on request. The default is 60.

failbackDelay

integer | null

required

≥ 0

Specifies the failback delay in seconds. The minimum value is 0. If specified, when a server has been down and comes back up, (that is, its liveness test starts succeeding again), GTM only considers it up after the failback delay has elapsed and tests continue to succeed.

failoverDelay

integer | null

required

≥ 0

Specifies the failover delay in seconds. The minimum value is 0. If specified, when a server begins failing its liveness test, GTM only considers it down after the failover delay has elapsed and the errors persist.

handoutMode

string

required

Specifies how IPs are returned when more than one IP is alive and available. Either normal, persistent, one-ip, one-ip-hashed, or all-live-ips. The default is normal. Handout mode is relevant only when you have more than one server IP in a data center.

normal persistent one-ip one-ip-hashed all-live-ips

healthMax

number | null

Defines the absolute limit beyond which IPs are declared unhealthy. If backup CNAMEs are provided for a property, then it is reasonable for all IPs to be declared unhealthy. The healthMax value is multiplied by the smaller of the timeoutPenalty and the errorPenalty. This check declares as down any server with a score greater than this product. The default value is null.

healthMultiplier

number | null

Configures a cutoff value that is computed from the median scores. Any server with a score over the cutoff value is considered down, and load isn't sent to it. The cutoff is computed from the minimum score across all data centers, for a given property and two object members: healthMultiplier and healthThreshold. The cutoff is either healthMultiplier (default value: 1.5) times the minimum score, or the healthThreshold (default value: 4), whichever is greater. See also healthThreshold within this object. For more information on how to determine server liveness, see the Global Traffic Management User Guide.

healthThreshold

number | null

Configures a cutoff value that is computed from the median scores. Any server with a score over the cutoff value is considered down, and load isn't sent to it. See also healthMultiplier within this object. For more information on how to determine server liveness, see the Global Traffic Management User Guide.

ipv6

boolean

required

Indicates the type of IP address handed out by a property. A true value indicates that all IP addresses specified are IPv6, and all hostnames need to resolve to AAAA records. A false value indicates IPv4 addresses, and all hostnames need to resolve to A records.

lastModified

date-time | null

An ISO 8601 timestamp that indicates when the property was last changed.

links

array of objects

Provides a URL path that allows direct navigation to the property.

links

object

href

string

Provides a hypermedia link to the complete URL that uniquely defines a resource.

rel

string

Indicates the link relationship of the object.

livenessTests

array of objects

required

Contains information about the liveness tests, which are run periodically to determine whether your servers respond to requests, as discussed in API concepts.

livenessTests*

object

disableNonstandardPortWarning

boolean

required

Disables warnings when non-standard ports are used. For example, GTM doesn't emit a warning to specify port 1234 when the testObjectProtocol is http, as HTTP typically uses port 80. The default is false.

hostHeader

string | null

required

Sent if the testObjectProtocol is http or https, up to 256 non-space, alphanumeric characters.

httpError3xx

boolean

required

Treats a 3xx HTTP response as a failure if the testObjectProtocol is http, https, or ftp.

httpError4xx

boolean

required

Treats a 4xx HTTP response as a failure if the testObjectProtocol is http, https, or ftp.

httpError5xx

boolean

required

Treats a 5xx HTTP response as a failure if the testObjectProtocol is http, https, or ftp.

name

string

required

length between 1 and 128

A descriptive name for the liveness test.

requestString

string | null

required

Specifies a request string. Required if testObjectProtocol is tcp or tcps. The value is a maximum of 4000 non-space, alphanumeric characters.

responseString

string | null

required

Specifies a response string. Required if testObjectProtocol is tcp or tcps. Maximum 4000 characters.

sslClientCertificate

string | null

required

Indicates a Base64-encoded certificate. SSL client certificates are available for livenessTests that use secure protocols.

sslClientPrivateKey

string | null

required

Indicates a Base64-encoded private key. The private key used to generate or request a certificate for livenessTests can't have a passphrase nor be used for any other purpose.

testInterval

integer

required

≥ 10

Indicates the interval at which the liveness test is run, in seconds. Requires a minimum of 10 seconds.

testObject

string | null

required

Specifies the static text that acts as a stand-in for the data that you're sending on the network.

testObjectPassword

string | null

required

Specifies the test object's password. It is required if testObjectProtocol is ftp. Maximum is 128 characters.

testObjectPort

integer

required

1 to 65535

Specifies the port number for the testObject. Value from 1 to 65535.

testObjectProtocol

string

required

Specifies the test protocol. Either DNS, DOH, DOT, HTTP, HTTPS, HTTP2, HTTP2S, FTP, POP, POPS, SMTP, SMTPS, TCP, or TCPS. To enable testObjectProtocol for DNS, DOH, or DOT requires application/vnd.config-gtm.v1.3+json.

HTTP HTTPS HTTP2 HTTP2S FTP POP POPS SMTP SMTPS TCP TCPS

testObjectUsername

string | null

required

A descriptive name for the testObject. If testObjectProtocol is ftp, then you need to specify a testObjectUsername. The value is a maximum of 256 non-space, alphanumeric characters.

testTimeout

number

required

≥ 0.001

Specifies the duration of the liveness test before it fails. The range is from 0.001 to 60 seconds.

loadImbalancePercentage

number | null

0 to 1000000

Indicates the percent of load imbalance factor (LIF) for the domain. It lets GTM exceed the value configured for traffic distribution. For example, if the data center's traffic allocation is 25 percent and the LIF is 1.5, the demand can grow to 37.5 percent (25% × 1.5) before the load balancer starts shifting load away from it. If the LIF is 0, no load imbalance is allowed. However, internally, GTM adds one to the LIF to allow its use as a multiplier. The default LIF is 1.1, which is displayed as 10.0 percent. The value ranges from 0 to 1000000 percent.

mapName

string | null

required

A descriptive label for a geographic map or a CIDR map that's required if the property is either geographic or cidrmapping, in which case mapName needs to reference either an existing geographic map or CIDR map in the same domain.

maxUnreachablePenalty

number | null

≥ 0

For performance domains, this specifies a penalty value that's added to liveness test scores when data centers show an aggregated loss fraction higher than the penalty value. The penalty value is either maxUnreachablePenalty (minimum value is 0 and the default is null) or unreachableThreshold (decimal between 0 and 1. A value of 1.0 or null disables an unreachable penalty). See also unreachableThreshold within this object.

mxRecords

array of objects

required

Specifies the MX records handed out to MX record type queries. Note that mapping and liveness testing aren't done. The same MX records are handed out for every request.

mxRecords*

object

exchange

string

required

MX record exchange member.

preference

number

required

MX record preference field.

name

string

required

length ≤ 256

The value, together with the full GTM domainName, forms the property's hostname. The value should not begin or end with a dot character and needs to be a valid RFC 1123 hostname. Set the name to @ if the property is to be located at the apex of the domain.

scoreAggregationType

string

required

Specifies how GTM aggregates liveness test scores across different tests, when multiple tests are configured. Values are mean, median, best, or the default worst.

mean median best worst

staticTTL

integer | null

required

30 to 3600

Specifies the TTL in seconds for static resource records that don't change based on the requesting name server IP. This includes MX, TXT, and SPF records.

stickinessBonusConstant

integer | null

0 to 30000

Specifies a constant used to configure data center affinity. This only applies if the property type is performance and the domain type is full. The value ranges from 0 to 30000. See also stickinessBonusPercentage within this object. To learn more about how these object members relate to each other, see API concepts.

stickinessBonusPercentage

integer | null

0 to 100

Specifies a percentage used to configure data center affinity. This only applies if the property type is performance and the domain type is full. The value ranges from 0 to 100. See also stickinessBonusConstant within this object. To learn more about how these object members relate to each other, see API concepts.

trafficTargets

array of objects

required

Contains information about where to direct data center traffic. For geographic mapped properties, it is always a cname. For mirror failover properties, it can be any set of servers. For load balanced properties, this is a set of servers that are all within the same data center. You can assign multiple traffic targets to the same data center.

trafficTargets*

object

datacenterId

integer

A unique identifier for an existing data center in the domain.

enabled

boolean

Indicates whether the traffic target is used. You can also omit the traffic target, which has the same result as the false value. However, when the value is false, GTM continues to store the other traffic target fields in the database. There's no need to store them locally should you want to use the traffic target at a later time.

handoutCName

string | null

Specifies an optional data center for the property. Uses the handoutCName when there are no servers configured for the property. Maximum 63 characters for the labels, 255 characters overall. May contain alphanumeric, hyphens, and underscores, but not literal IP addresses. Leading or trailing hyphens are not allowed.

name

string | null

An alternative label for the traffic target.

servers

array of strings

Identifies the IP address or the hostnames of the servers. For hostnames that return IP addresses, tests all IP addresses for liveness.

servers

weight

number

≥ 0

Specifies the traffic weight for the target. This member is required when the enclosing property is failover, weighted, weighted-with-load-feedback, or performance. The sum of this value, for all enabled targets, can be any number, percentage, or ratio. For example, you can express a traffic split as 60/40, 120/80, or 3/2, all equivalent values. For failover properties, set this value to 1 for the traffic target you want to mark as primary.

type

string

required

Specifies the load balancing behavior for the property. Either failover, geographic, cidrmapping, weighted-round-robin, weighted-hashed, weighted-round-robin-load-feedback, qtr, or performance. An additional value of asmapping requires the application/vnd.config-gtm.v1.1+json media type. See API versioning for more information.

failover geographic cidrmapping weighted-round-robin weighted-hashed weighted-round-robin-load-feedback qtr performance

unreachableThreshold

number | null

0 to 1

For performance domains, this specifies a penalty value that's added to liveness test scores when data centers have an aggregated loss fraction higher than this value. The value is a decimal between 0 and 1. A value of 1.0 or null disables an unreachable penalty. See also maxUnreachablePenalty within this object.

useComputedTargets

boolean

For load-feedback domains only, this specifies that you want GTM to automatically compute target load. Report only the current load objects, either by omission, or by using non-XML load objects.

200Successful response.