Skip to content

Health checks

All operations require authentication.

6 operationsv2/dns/gslb
View as Markdown (opens in a new tab)
Agent setup

List GSLB health checksAlpha

GET
/v2/dns/gslb/healthCheck

Query parameters

iamTags
object

Filter resources on IAM tags

Headers

X-Pagination-Cursor
string

Pagination cursor

X-Pagination-Size
integer

Pagination size

Response

200HealthCheckWithIAM[]successful operation
createdAt
read-only
stringdate-time

Creation timestamp

disabled
read-only
boolean

Whether check execution is disabled

dnsQueryName
read-only
string

Name queried by DNS health checks, required for the DNS type. Null when not set.

dnsRecordType
read-only
HealthCheckRecordTypeEnum

Record type queried by DNS health checks, required for the DNS type. Null when not set.

ValuesAAAAACNAMEMXTXT
failureThreshold
read-only
integer

Consecutive failures before marking the endpoint unhealthy

fqdn
read-only
string

FQDN used for the HTTP Host header and TLS SNI. Null when the check targets only ipAddress.

healthStatus
read-only
HealthStatusEnum

Current endpoint health

ValuesHEALTHYUNHEALTHYUNKNOWN
iam
read-only
ResourceMetadata

IAM resource metadata

id
read-only
stringuuid

Unique identifier of the health check

inverted
read-only
boolean

Whether health status is inverted

ipAddress
read-only
ip

Public IPv4 or IPv6 endpoint address. Null when the check targets only fqdn.

lastCheckedAt
read-only
stringdate-time

Last execution timestamp. Null until the first check has run.

lastError
read-only
string

Error of the most recent check. Null when that check succeeded or no check has run yet.

name
read-only
string

Optional health check name

port
read-only
integer

Endpoint port, null for protocols that do not use one, such as ICMP

requestInterval
read-only
integer

Interval between checks, 10 or 30 seconds

resourcePath
read-only
string

HTTP request path, required for the HTTP, HTTPS, HTTP_STR_MATCH and HTTPS_STR_MATCH types. Null when not set.

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
searchString
read-only
string

String expected in the HTTP response body, required for the HTTP_STR_MATCH and HTTPS_STR_MATCH types. Null when not set.

type
read-only
HealthCheckTypeEnum

Health check protocol

ValuesDNSHTTPHTTPSHTTPS_STR_MATCHHTTP_STR_MATCHICMPTCP
updatedAt
read-only
stringdate-time

Last modification timestamp

400objectError 400 response

Reads your token from $OVH_TOKEN

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/healthCheck \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
[ { "createdAt": "2024-01-01T12:00:00Z", "disabled": true, "dnsQueryName": "string", "dnsRecordType": "A", "failureThreshold": 0, "fqdn": "string", "healthStatus": "HEALTHY", "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "00000000-0000-0000-0000-000000000000", "inverted": true, "ipAddress": "192.0.2.0", "lastCheckedAt": "2024-01-01T12:00:00Z", "lastError": "string", "name": "string", "port": 0, "requestInterval": 0, "resourcePath": "string", "resourceStatus": "CREATING", "searchString": "string", "type": "DNS", "updatedAt": "2024-01-01T12:00:00Z" }]

Get a GSLB health checkAlpha

GET
/v2/dns/gslb/healthCheck/{healthCheckId}

Path parameters

healthCheckId
required
stringuuid

Health check ID

Response

200HealthCheckWithIAMsuccessful operation
createdAt
read-only
stringdate-time

Creation timestamp

disabled
read-only
boolean

Whether check execution is disabled

dnsQueryName
read-only
string

Name queried by DNS health checks, required for the DNS type. Null when not set.

dnsRecordType
read-only
HealthCheckRecordTypeEnum

Record type queried by DNS health checks, required for the DNS type. Null when not set.

ValuesAAAAACNAMEMXTXT
failureThreshold
read-only
integer

Consecutive failures before marking the endpoint unhealthy

fqdn
read-only
string

FQDN used for the HTTP Host header and TLS SNI. Null when the check targets only ipAddress.

healthStatus
read-only
HealthStatusEnum

Current endpoint health

ValuesHEALTHYUNHEALTHYUNKNOWN
iam
read-only
ResourceMetadata

IAM resource metadata

id
read-only
stringuuid

Unique identifier of the health check

inverted
read-only
boolean

Whether health status is inverted

ipAddress
read-only
ip

Public IPv4 or IPv6 endpoint address. Null when the check targets only fqdn.

lastCheckedAt
read-only
stringdate-time

Last execution timestamp. Null until the first check has run.

lastError
read-only
string

Error of the most recent check. Null when that check succeeded or no check has run yet.

name
read-only
string

Optional health check name

port
read-only
integer

Endpoint port, null for protocols that do not use one, such as ICMP

requestInterval
read-only
integer

Interval between checks, 10 or 30 seconds

resourcePath
read-only
string

HTTP request path, required for the HTTP, HTTPS, HTTP_STR_MATCH and HTTPS_STR_MATCH types. Null when not set.

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
searchString
read-only
string

String expected in the HTTP response body, required for the HTTP_STR_MATCH and HTTPS_STR_MATCH types. Null when not set.

type
read-only
HealthCheckTypeEnum

Health check protocol

ValuesDNSHTTPHTTPSHTTPS_STR_MATCHHTTP_STR_MATCHICMPTCP
updatedAt
read-only
stringdate-time

Last modification timestamp

404objectError 404 response

Example uses healthCheckId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/healthCheck/{healthCheckId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "createdAt": "2024-01-01T12:00:00Z", "disabled": true, "dnsQueryName": "string", "dnsRecordType": "A", "failureThreshold": 0, "fqdn": "string", "healthStatus": "HEALTHY", "iam": { "displayName": "string", "id": "00000000-0000-0000-0000-000000000000", "state": "EXPIRED", "tags": { "key": "string" }, "urn": "string" }, "id": "00000000-0000-0000-0000-000000000000", "inverted": true, "ipAddress": "192.0.2.0", "lastCheckedAt": "2024-01-01T12:00:00Z", "lastError": "string", "name": "string", "port": 0, "requestInterval": 0, "resourcePath": "string", "resourceStatus": "CREATING", "searchString": "string", "type": "DNS", "updatedAt": "2024-01-01T12:00:00Z"}

Create a GSLB health checkAlpha

POST
/v2/dns/gslb/healthCheck

Request body (required)

disabled
boolean

Disable execution. Defaults to false.

dnsQueryName
string

Name queried by DNS health checks

dnsRecordType
HealthCheckRecordTypeEnum

Record type queried by DNS health checks

ValuesAAAAACNAMEMXTXT
failureThreshold
integer

Consecutive failures from 1 to 10. Defaults to 3.

fqdn
string

FQDN for the HTTP Host header and TLS SNI

inverted
boolean

Invert health status. Defaults to false.

ipAddress
ip

Public IPv4 or IPv6 endpoint address. Private and loopback addresses are rejected. Required for ICMP, and for other protocols unless fqdn is set.

name
string

Optional name. At most 255 characters.

port
integer

Endpoint port from 1 to 65535 when required by the protocol

requestInterval
integer

Interval of 10 or 30 seconds. Defaults to 30.

resourcePath
string

HTTP request path starting with /. At most 255 characters.

searchString
string

Expected response text for HTTP_STR_MATCH or HTTPS_STR_MATCH

type
required
HealthCheckTypeEnum

Health check protocol. Immutable after creation.

ValuesDNSHTTPHTTPSHTTPS_STR_MATCHHTTP_STR_MATCHICMPTCP

Response

200HealthChecksuccessful operation
createdAt
read-only
stringdate-time

Creation timestamp

disabled
read-only
boolean

Whether check execution is disabled

dnsQueryName
read-only
string

Name queried by DNS health checks, required for the DNS type. Null when not set.

dnsRecordType
read-only
HealthCheckRecordTypeEnum

Record type queried by DNS health checks, required for the DNS type. Null when not set.

ValuesAAAAACNAMEMXTXT
failureThreshold
read-only
integer

Consecutive failures before marking the endpoint unhealthy

fqdn
read-only
string

FQDN used for the HTTP Host header and TLS SNI. Null when the check targets only ipAddress.

healthStatus
read-only
HealthStatusEnum

Current endpoint health

ValuesHEALTHYUNHEALTHYUNKNOWN
id
read-only
stringuuid

Unique identifier of the health check

inverted
read-only
boolean

Whether health status is inverted

ipAddress
read-only
ip

Public IPv4 or IPv6 endpoint address. Null when the check targets only fqdn.

lastCheckedAt
read-only
stringdate-time

Last execution timestamp. Null until the first check has run.

lastError
read-only
string

Error of the most recent check. Null when that check succeeded or no check has run yet.

name
read-only
string

Optional health check name

port
read-only
integer

Endpoint port, null for protocols that do not use one, such as ICMP

requestInterval
read-only
integer

Interval between checks, 10 or 30 seconds

resourcePath
read-only
string

HTTP request path, required for the HTTP, HTTPS, HTTP_STR_MATCH and HTTPS_STR_MATCH types. Null when not set.

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
searchString
read-only
string

String expected in the HTTP response body, required for the HTTP_STR_MATCH and HTTPS_STR_MATCH types. Null when not set.

type
read-only
HealthCheckTypeEnum

Health check protocol

ValuesDNSHTTPHTTPSHTTPS_STR_MATCHHTTP_STR_MATCHICMPTCP
updatedAt
read-only
stringdate-time

Last modification timestamp

400objectError 400 response

Reads your token from $OVH_TOKEN

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/healthCheck \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "createdAt": "2024-01-01T12:00:00Z", "disabled": true, "dnsQueryName": "string", "dnsRecordType": "A", "failureThreshold": 0, "fqdn": "string", "healthStatus": "HEALTHY", "id": "00000000-0000-0000-0000-000000000000", "inverted": true, "ipAddress": "192.0.2.0", "lastCheckedAt": "2024-01-01T12:00:00Z", "lastError": "string", "name": "string", "port": 0, "requestInterval": 0, "resourcePath": "string", "resourceStatus": "CREATING", "searchString": "string", "type": "DNS", "updatedAt": "2024-01-01T12:00:00Z"}

Update a GSLB health check. Its protocol type is immutable.Alpha

PATCH
/v2/dns/gslb/healthCheck/{healthCheckId}

Path parameters

healthCheckId
required
stringuuid

Health check ID

Request body (required)

disabled
boolean

Whether to disable check execution. When null, checks are enabled.

dnsQueryName
string

New name queried by DNS health checks. When null, the name is removed.

dnsRecordType
HealthCheckRecordTypeEnum

New record type queried by DNS health checks. When null, the record type is removed.

ValuesAAAAACNAMEMXTXT
failureThreshold
integer

New number of consecutive failures. When null, the default of 3 is restored. From 1 to 10.

fqdn
string

New FQDN for the HTTP Host header and TLS SNI. When null, the FQDN is removed.

inverted
boolean

Whether to invert the health status. When null, the health status is not inverted.

ipAddress
ip

New public IPv4 or IPv6 endpoint address. When null, the address is removed.

name
string

New health check name. When null, the name is removed.

port
integer

New endpoint port. When null, the port is removed, which is only valid for protocols that do not use a port, such as ICMP. From 1 to 65535.

requestInterval
integer

New interval of 10 or 30 seconds. When null, the default of 30 is restored.

resourcePath
string

New HTTP request path starting with /. When null, the path is removed.

searchString
string

New expected HTTP response text. When null, the text is removed.

Response

200HealthChecksuccessful operation
createdAt
read-only
stringdate-time

Creation timestamp

disabled
read-only
boolean

Whether check execution is disabled

dnsQueryName
read-only
string

Name queried by DNS health checks, required for the DNS type. Null when not set.

dnsRecordType
read-only
HealthCheckRecordTypeEnum

Record type queried by DNS health checks, required for the DNS type. Null when not set.

ValuesAAAAACNAMEMXTXT
failureThreshold
read-only
integer

Consecutive failures before marking the endpoint unhealthy

fqdn
read-only
string

FQDN used for the HTTP Host header and TLS SNI. Null when the check targets only ipAddress.

healthStatus
read-only
HealthStatusEnum

Current endpoint health

ValuesHEALTHYUNHEALTHYUNKNOWN
id
read-only
stringuuid

Unique identifier of the health check

inverted
read-only
boolean

Whether health status is inverted

ipAddress
read-only
ip

Public IPv4 or IPv6 endpoint address. Null when the check targets only fqdn.

lastCheckedAt
read-only
stringdate-time

Last execution timestamp. Null until the first check has run.

lastError
read-only
string

Error of the most recent check. Null when that check succeeded or no check has run yet.

name
read-only
string

Optional health check name

port
read-only
integer

Endpoint port, null for protocols that do not use one, such as ICMP

requestInterval
read-only
integer

Interval between checks, 10 or 30 seconds

resourcePath
read-only
string

HTTP request path, required for the HTTP, HTTPS, HTTP_STR_MATCH and HTTPS_STR_MATCH types. Null when not set.

resourceStatus
read-only
ResourceStatusEnum

Resource lifecycle status

ValuesCREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATING
searchString
read-only
string

String expected in the HTTP response body, required for the HTTP_STR_MATCH and HTTPS_STR_MATCH types. Null when not set.

type
read-only
HealthCheckTypeEnum

Health check protocol

ValuesDNSHTTPHTTPSHTTPS_STR_MATCHHTTP_STR_MATCHICMPTCP
updatedAt
read-only
stringdate-time

Last modification timestamp

400objectError 400 response
404objectError 404 response

Example uses healthCheckId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/healthCheck/{healthCheckId} \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "createdAt": "2024-01-01T12:00:00Z", "disabled": true, "dnsQueryName": "string", "dnsRecordType": "A", "failureThreshold": 0, "fqdn": "string", "healthStatus": "HEALTHY", "id": "00000000-0000-0000-0000-000000000000", "inverted": true, "ipAddress": "192.0.2.0", "lastCheckedAt": "2024-01-01T12:00:00Z", "lastError": "string", "name": "string", "port": 0, "requestInterval": 0, "resourcePath": "string", "resourceStatus": "CREATING", "searchString": "string", "type": "DNS", "updatedAt": "2024-01-01T12:00:00Z"}

Delete a health check not referenced by any record setAlpha

DELETE
/v2/dns/gslb/healthCheck/{healthCheckId}

Path parameters

healthCheckId
required
stringuuid

Health check ID

Response

200—successful operation

Example uses healthCheckId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/healthCheck/{healthCheckId} \
  -H "authorization: Bearer $OVH_TOKEN"

Get the current status of a GSLB health checkAlpha

GET
/v2/dns/gslb/healthCheck/{healthCheckId}/status

Path parameters

healthCheckId
required
stringuuid

Health check ID

Response

200HealthCheckStatussuccessful operation
healthCheckId
read-only
stringuuid

Identifier of the health check

lastCheckedAt
read-only
stringdate-time

Last execution timestamp. Null until the first check has run.

status
read-only
HealthStatusEnum

Current endpoint health

ValuesHEALTHYUNHEALTHYUNKNOWN
404objectError 404 response

Example uses healthCheckId = 00000000-0000-0000-0000-000000000000

$ curl https://api.eu.ovhcloud.com/v2/dns/gslb/healthCheck/{healthCheckId}/status \
  -H "authorization: Bearer $OVH_TOKEN"
ResponseExample
{ "healthCheckId": "00000000-0000-0000-0000-000000000000", "lastCheckedAt": "2024-01-01T12:00:00Z", "status": "HEALTHY"}