Skip to main content

StatusCake API (1.2.0)

Download OpenAPI specification:Download

StatusCake API endpoints to manage monitoring resources.

Authentication

Documentation on API authentication can be found here.

Ratelimiting

Documentation on API ratelimiting can be found here.

Errors

Documentation on error handling can be found here.

Handling Input Parameters

Documentation on input parameters, including how to pass arrays to API endpoints can be found here.

heartbeat

The Heartbeat API provides methods to operate on heartbeat resources, effectively allowing checks to be read and listed.

Get all heartbeat checks

Returns a list of heartbeat checks for an account.

query Parameters
status
string
Enum: "down" "up"

Heartbeat check status

page
integer <int32> >= 1
Default: 1

Page of results

limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of heartbeat checks to return per page

tags
string

Comma separated list of tags assocaited with a check

matchany
boolean
Default: false

Include heartbeat checks in response that match any specified tag or all tags. This parameter does not take a value. The absence of this paratemer equates to false whilst the presence of thie paramerter equates to true.

nouptime
boolean
Default: false

Do not calculate uptime percentages for results. This parameter does not take a value. The absence of this paratemer equates to false whilst the presence of thie paramerter equates to true.

Responses

Response Schema: application/json
required
Array of objects (HeartbeatTestOverview)

List of heartbeat checks

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/heartbeat \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

Create a heartbeat check

Creates a heartbeat check with the given parameters.

Request Body schema: application/x-www-form-urlencoded
name
required
string

Name of the check

period
required
integer <int32> [ 30 .. 172800 ]
Default: 1800

Number of seconds since the last ping before the check is considered down

contact_groups
Array of strings

List of contact group IDs

host
string

Name of the hosting provider

paused
boolean
Default: false

Whether the check should be run

tags
Array of strings

List of tags

Responses

Request samples

curl -X POST https://api.statuscake.com/v1/heartbeat \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example%20Heartbeat&period=1800"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a heartbeat check

Returns a heartbeat check with the given id.

path Parameters
test_id
required
string

Heartbeat check ID

Responses

Response Schema: application/json
required
object (HeartbeatTest)
id
required
string

Heartbeat check ID

name
required
string

Name of the check

url
required
string <uri>

URL of the check

period
required
integer <int32> [ 30 .. 172800 ]

Number of seconds since the last ping before the check is considered down

contact_groups
required
Array of strings

List of contact group IDs

host
string

Name of the hosting provider

last_tested_at
string <date-time>

When the check was last run (RFC3339 format)

paused
required
boolean

Whether the check should be run

status
required
string (HeartbeatTestStatus)
Enum: "down" "up"

The returned status of a heartbeat check

tags
required
Array of strings

List of tags

uptime
required
number <float> >= 0

Uptime percentage for a check

Request samples

curl https://api.statuscake.com/v1/heartbeat/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

Update a heartbeat check

Updates a heartbeat check with the given parameters.

path Parameters
test_id
required
string

Heartbeat check ID

Request Body schema: application/x-www-form-urlencoded
name
string

Name of the check

period
integer <int32> [ 30 .. 172800 ]

Number of seconds since the last ping before the check is considered down

contact_groups
Array of strings

List of contact group IDs

host
string

Name of the hosting provider

paused
boolean

Whether the check should be run

tags
Array of strings

List of tags

Responses

Request samples

curl -X PUT https://api.statuscake.com/v1/heartbeat/123 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example%20Heartbeat&period=1800"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

Delete a heartbeat check

Deletes a heartbeat check with the given id.

path Parameters
test_id
required
string

Heartbeat check ID

Responses

Request samples

curl -X DELETE https://api.statuscake.com/v1/heartbeat/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

pagespeed

The Pagespeed API provides methods to operate on pagespeed resources, effectively allowing checks to be created, read, updated, and deleted. In addition the history of a specific pagespeed check can be returned for a given period.

Get all pagespeed checks

Returns a list of pagespeed checks for an account.

query Parameters
page
integer <int32> >= 1
Default: 1

Page of results

limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of pagespeed checks to return per page

Responses

Response Schema: application/json
required
Array of objects (PagespeedTest)

List of pagespeed checks

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/pagespeed \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

Create a pagespeed check

Creates a pagespeed check with the given parameters.

Request Body schema: application/x-www-form-urlencoded
name
required
string

Name of the check

website_url
required
string <uri>

URL, FQDN, or IP address of the website under test

check_rate
required
integer (PagespeedTestCheckRate)
Enum: 60 300 600 900 1800 3600 86400

Number of seconds between checks

alert_bigger
integer <int32> >= 0
Default: 0

An alert will be sent if the size of the page is larger than this value (kb). A value of 0 prevents alerts being sent.

alert_slower
integer <int64> >= 0
Default: 0

An alert will be sent if the load time of the page exceeds this value (ms). A value of 0 prevents alerts being sent

alert_smaller
integer <int32> >= 0
Default: 0

An alert will be sent if the size of the page is smaller than this value (kb). A value of 0 prevents alerts being sent

contact_groups
Array of strings

List of contact group IDs

paused
boolean
Default: false

Whether the check should be run

region
required
string (PagespeedTestRegion)
Enum: "AU" "CA" "DE" "FR" "IN" "JP" "NL" "SG" "UK" "US" "USW"

Region on which to run checks

Responses

Request samples

curl -X POST https://api.statuscake.com/v1/pagespeed \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example&website_url=https://www.example.com&region=UK&check_rate=10"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a pagespeed check

Returns a pagespeed check with the given id.

path Parameters
test_id
required
string

Pagespeed check ID

Responses

Response Schema: application/json
required
object (PagespeedTest)
id
required
string

Pagespeed check ID

name
required
string

Name of the check

website_url
required
string <uri>

URL, FQDN, or IP address of the website under test

check_rate
required
integer (PagespeedTestCheckRate)
Enum: 60 300 600 900 1800 3600 86400

Number of seconds between checks

alert_bigger
required
integer <int32> >= 0

An alert will be sent if the size of the page is larger than this value (kb). A value of 0 prevents alerts being sent.

alert_slower
required
integer <int64> >= 0

An alert will be sent if the load time of the page exceeds this value (ms). A value of 0 prevents alerts being sent

alert_smaller
required
integer <int32> >= 0

An alert will be sent if the size of the page is smaller than this value (kb). A value of 0 prevents alerts being sent

contact_groups
required
Array of strings

List of contact group IDs

object (PagespeedTestStats)
location
required
string

Assigned monitoring location on which checks will be run

paused
required
boolean

Whether the check should be run

Request samples

curl https://api.statuscake.com/v1/pagespeed/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a pagespeed check

Updates a pagespeed check with the given parameters.

path Parameters
test_id
required
string

Pagespeed check ID

Request Body schema: application/x-www-form-urlencoded
name
string

Name of the check

website_url
string <uri>

URL, FQDN, or IP address of the website under test

check_rate
integer (PagespeedTestCheckRate)
Enum: 60 300 600 900 1800 3600 86400

Number of seconds between checks

alert_bigger
integer <int32> >= 0

An alert will be sent if the size of the page is larger than this value (kb). A value of 0 prevents alerts being sent.

alert_slower
integer <int64> >= 0

An alert will be sent if the load time of the page exceeds this value (ms). A value of 0 prevents alerts being sent

alert_smaller
integer <int32> >= 0

An alert will be sent if the size of the page is smaller than this value (kb). A value of 0 prevents alerts being sent

contact_groups
Array of strings

List of contact group IDs

paused
boolean

Whether the check should be run

region
string (PagespeedTestRegion)
Enum: "AU" "CA" "DE" "FR" "IN" "JP" "NL" "SG" "UK" "US" "USW"

Region on which to run checks

Responses

Request samples

curl -X PUT https://api.statuscake.com/v1/pagespeed/123 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example&region=UK&check_rate=10"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

Delete a pagespeed check

Deletes a pagespeed check with the given id.

path Parameters
test_id
required
string

Pagespeed check ID

Responses

Request samples

curl -X DELETE https://api.statuscake.com/v1/pagespeed/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

Get all pagespeed check history

Returns a list of pagespeed check history results for a given id, detailing the runs performed on the StatusCake testing infrastruture.

The returned results are a paginated series. Alongside the response data is a links object referencing the current response document, self, and the next page in the series, next.

Aggregated data over the specified duration is returned in the root level metadata field.

path Parameters
test_id
required
string

Pagespeed check ID

query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of results to return from the series

before
integer <int64> >= 0

Only results created before this UNIX timestamp will be returned

after
integer <int64> >= 0

Only results created after this UNIX timestamp will be returned

Responses

Response Schema: application/json
required
Array of objects (PagespeedTestHistoryResult)

List of pagespeed check history results

required
object (Links)
object (Metadata)

Request samples

curl https://api.statuscake.com/v1/pagespeed/123/history \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

ssl

The SSL API provides methods to operate on SSL resources, effectively allowing checks to be created, read, updated, and deleted.

Get all SSL checks

Returns a list of SSL checks for an account.

query Parameters
page
integer <int32> >= 1
Default: 1

Page of results

limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of SSL checks to return per page

Responses

Response Schema: application/json
required
Array of objects (SSLTest)

List of SSL checks

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/ssl \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

Create an SSL check

Creates an SSL check with the given parameters.

Request Body schema: application/x-www-form-urlencoded
website_url
required
string <uri>

URL of the server under test. Must begin with https://

check_rate
required
integer (SSLTestCheckRate)
Enum: 300 600 1800 3600 86400 2073600

Number of seconds between checks

alert_at
required
Array of integers <int32> [ items <int32 > ]

List representing when alerts should be sent (days). Must be exactly 3 numerical values

alert_broken
boolean
Default: false

Whether to enable alerts when SSL certificate issues are found

alert_expiry
boolean
Default: false

Whether to enable alerts when the SSL certificate is to expire

alert_mixed
boolean
Default: false

Whether to enable alerts when mixed content is found

alert_reminder
boolean
Default: false

Whether to enable alert reminders

contact_groups
Array of strings

List of contact group IDs

follow_redirects
boolean
Default: false

Whether to follow redirects when testing. Disabled by default

hostname
string

Hostname of the server under test

paused
boolean
Default: false

Whether the check should be run

user_agent
string

Custom user agent string set when testing

Responses

Request samples

curl -X POST https://api.statuscake.com/v1/ssl \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "website_url=https://www.example.com&check_rate=1800&alert_at[]=1&alert_at[]=2&alert_at[]=3&alert_reminder=true&alert_expiry=true&alert_broken=true&alert_mixed=true"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve an SSL check

Returns an SSL check with the given id.

path Parameters
test_id
required
string

SSL check ID

Responses

Response Schema: application/json
required
object (SSLTest)
id
required
string

SSL check ID

website_url
required
string <uri>

URL of the server under test

check_rate
required
integer (SSLTestCheckRate)
Enum: 300 600 1800 3600 86400 2073600

Number of seconds between checks

alert_at
required
Array of integers <int32> [ items <int32 > ]

List representing when alerts should be sent (days).

alert_broken
required
boolean

Whether to enable alerts when SSL certificate issues are found

alert_expiry
required
boolean

Whether to enable alerts when the SSL certificate is to expire

alert_mixed
required
boolean

Whether to enable alerts when mixed content is found

alert_reminder
required
boolean

Whether to enable alert reminders

certificate_score
integer <int32> [ 0 .. 100 ]

SSL certificate score (%)

certificate_status
string

SSL certificate status

cipher
string

SSL/TLS cipher suite belonging to the SSL certificate

cipher_score
integer <int32> [ 0 .. 100 ]

SSL certificate cipher strength (%)

contact_groups
required
Array of strings

List of contact group IDs

issuer_common_name
string

Issuer of the SSL certificate

object (SSLTestFlags)
follow_redirects
required
boolean

Whether to follow redirects when testing. Disabled by default

hostname
string

Hostname of the server under test

last_reminder
integer <int32> >= 0

The last reminder to have been sent (days)

required
Array of objects (SSLTestMixedContent)

List of mixed content resources

paused
required
boolean

Whether the check should be run

updated_at
string <date-time>

When the SSL certificate was last updated (RFC3339 format)

user_agent
string

Custom user agent string set when testing

valid_from
string <date-time>

SSL certificate validity start (RFC3339 format)

valid_until
string <date-time>

SSL certificate validity end (RFC3339 format)

Request samples

curl https://api.statuscake.com/v1/ssl/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an SSL check

Updates an SSL check with the given parameters.

path Parameters
test_id
required
string

SSL check ID

Request Body schema: application/x-www-form-urlencoded
website_url
string <uri>

URL of the server under test. Must begin with https://

check_rate
integer (SSLTestCheckRate)
Enum: 300 600 1800 3600 86400 2073600

Number of seconds between checks

alert_at
Array of integers <int32> [ items <int32 > ]

List representing when alerts should be sent (days). Must be exactly 3 numerical values

alert_broken
boolean

Whether to enable alerts when SSL certificate issues are found

alert_expiry
boolean

Whether to enable alerts when the SSL certificate is to expire

alert_mixed
boolean

Whether to enable alerts when mixed content is found

alert_reminder
boolean

Whether to enable alert reminders

contact_groups
Array of strings

List of contact group IDs

follow_redirects
boolean

Whether to follow redirects when testing. Disabled by default

hostname
string

Hostname of the server under test

paused
boolean

Whether the check should be run

user_agent
string

Custom user agent string set when testing

Responses

Request samples

curl -X PUT https://api.statuscake.com/v1/ssl/123 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "check_rate=1800&alert_at[]=1&alert_at[]=2&alert_at[]=3&alert_reminder=true&alert_expiry=true&alert_broken=true&alert_mixed=true"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

Delete an SSL check

Deletes an SSL check with the given id.

path Parameters
test_id
required
string

Pagespeed check ID

Responses

Request samples

curl -X DELETE https://api.statuscake.com/v1/ssl/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

uptime

The Uptime API provides methods to operate on uptime resources, effectively allowing checks to be created, read, updated, and deleted. In addition the Uptime API is able to return a history of uptime status for a given period; and return a history of alerts since a given date.

Get all uptime checks

Returns a list of uptime checks for an account.

query Parameters
status
string
Enum: "down" "up"

Uptime check status

page
integer <int32> >= 1
Default: 1

Page of results

limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of uptime checks to return per page

tags
string

Comma separated list of tags assocaited with a check

matchany
boolean
Default: false

Include uptime checks in response that match any specified tag or all tags. This parameter does not take a value. The absence of this paratemer equates to false whilst the presence of thie paramerter equates to true.

nouptime
boolean
Default: false

Do not calculate uptime percentages for results. This parameter does not take a value. The absence of this paratemer equates to false whilst the presence of thie paramerter equates to true.

Responses

Response Schema: application/json
required
Array of objects (UptimeTestOverview)

List of uptime checks

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/uptime \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

Create an uptime check

Creates an uptime check with the given parameters.

Request Body schema: application/x-www-form-urlencoded
name
required
string

Name of the check

test_type
required
string (UptimeTestType)
Enum: "DNS" "HEAD" "HTTP" "PING" "SMTP" "SSH" "TCP"

Uptime check type

website_url
required
string <uri>

URL or IP address of the server under test

check_rate
required
integer (UptimeTestCheckRate)
Enum: 0 30 60 300 900 1800 3600 86400

Number of seconds between checks

basic_username
string

Basic authentication username

basic_password
string

Basic authentication password

confirmation
integer <int32> [ 0 .. 3 ]
Default: 2

Number of confirmation servers to confirm downtime before an alert is triggered

contact_groups
Array of strings

List of contact group IDs

custom_header
string

JSON object. Represents headers to be sent when making requests

do_not_find
boolean
Default: false

Whether to consider the check as down if the content is present within the response

dns_ips
Array of strings

List of IP addresses to compare against returned DNS records

dns_server
string

FQDN or IP address of the nameserver to query

enable_ssl_alert
boolean
Default: false

Whether to send an alert if the SSL certificate is soon to expire

final_endpoint
string

Specify where the redirect chain should end

find_string
string

String to look for within the response. Considered down if not found

follow_redirects
boolean
Default: false

Whether to follow redirects when testing. Disabled by default

host
string

Name of the hosting provider

include_header
boolean
Default: false

Include header content in string match search

paused
boolean
Default: false

Whether the check should be run

port
integer <int32> >= 0

Destination port for TCP checks

post_body
string

JSON object. Payload submitted with the request. Setting this updates the check to use the HTTP POST verb

post_raw
string

Raw HTTP POST string to send to the server

regions
Array of strings

List of regions on which to run checks. The values required for this parameter can be retrieved from the GET /v1/uptime-locations endpoint.

status_codes_csv
string

Comma separated list of status codes that trigger an alert

tags
Array of strings

List of tags

timeout
integer <int32> [ 5 .. 75 ]
Default: 15

The number of seconds to wait to receive the first byte

trigger_rate
integer <int32> [ 0 .. 60 ]
Default: 0

The number of minutes to wait before sending an alert

use_jar
boolean
Default: false

Whether to enable cookie storage

user_agent
string

Custom user agent string set when testing

Responses

Request samples

curl -X POST https://api.statuscake.com/v1/uptime \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example%20HTTP&test_type=HTTP&website_url=https://www.example.com&check_rate=1800&regions[]=london&regions[]=paris"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve an uptime check

Returns an uptime check with the given id.

path Parameters
test_id
required
string

Uptime check ID

Responses

Response Schema: application/json
required
object (UptimeTest)
id
required
string

Uptime check ID

name
required
string

Name of the check

test_type
required
string (UptimeTestType)
Enum: "DNS" "HEAD" "HTTP" "PING" "SMTP" "SSH" "TCP"

Uptime check type

website_url
required
string <uri>

URL, FQDN, or IP address of the server under test

check_rate
required
integer (UptimeTestCheckRate)
Enum: 0 30 60 300 900 1800 3600 86400

Number of seconds between checks

confirmation
required
integer <int32> [ 0 .. 3 ]

Number of confirmation servers to confirm downtime before an alert is triggered

contact_groups
required
Array of strings

List of contact group IDs

custom_header
string

JSON object. Represents headers to be sent when making requests

dns_ips
required
Array of strings

List of IP addresses to compare against returned DNS records

dns_server
string

FQDN or IP address of the nameserver to query

do_not_find
required
boolean

Whether to consider the check as down if the content is present within the response

enable_ssl_alert
required
boolean

Whether to send an alert if the SSL certificate is soon to expire

final_endpoint
string

Specify where the redirect chain should end

find_string
string

String to look for within the response. Considered down if not found

follow_redirects
required
boolean

Whether to follow redirects when testing. Disabled by default

include_header
required
boolean

Include header content in string match search

host
string

Name of the hosting provider

last_tested_at
string <date-time>

When the check was last run (RFC3339 format)

next_location
string

The server location the check will run next

paused
required
boolean

Whether the check should be run

port
integer <int32> >= 0

Destination port for TCP checks

post_body
string

JSON object. Payload submitted with the request. Setting this updates the check to use the HTTP POST verb

post_raw
string

Raw HTTP POST string to send to the server

processing
required
boolean

Whether the check is currently being processed

processing_on
string

The server location the check is currently being run

processing_state
string (UptimeTestProcessingState)
Enum: "complete" "pretest" "retest" "up_retest"

Uptime check proccessing state

required
Array of objects (MonitoringLocation)

List of assigned monitoring locations on which to run checks

status
required
string (UptimeTestStatus)
Enum: "down" "up"

The returned status of an uptime check

status_codes
required
Array of strings

List of status codes that trigger an alert

tags
required
Array of strings

List of tags

timeout
required
integer <int32> [ 5 .. 75 ]

The number of seconds to wait to receive the first byte

trigger_rate
required
integer <int32> [ 0 .. 60 ]

The number of minutes to wait before sending an alert

uptime
required
number <float> >= 0

Uptime percentage for a check

use_jar
required
boolean

Whether to enable cookie storage

user_agent
string

Custom user agent string set when testing

Request samples

curl https://api.statuscake.com/v1/uptime/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update an uptime check

Updates an uptime check with the given parameters.

path Parameters
test_id
required
string

Uptime check ID

Request Body schema: application/x-www-form-urlencoded
name
string

Name of the check

website_url
string <uri>

URL or IP address of the server under test

check_rate
integer (UptimeTestCheckRate)
Enum: 0 30 60 300 900 1800 3600 86400

Number of seconds between checks

basic_username
string

Basic authentication username

basic_password
string

Basic authentication password

confirmation
integer <int32> [ 0 .. 3 ]

Number of confirmation servers to confirm downtime before an alert is triggered

contact_groups
Array of strings

List of contact group IDs

custom_header
string

JSON object. Represents headers to be sent when making requests

do_not_find
boolean

Whether to consider the check as down if the content is present within the response

dns_ips
Array of strings

List of IP addresses to compare against returned DNS records

dns_server
string

FQDN or IP address of the nameserver to query

enable_ssl_alert
boolean

Whether to send an alert if the SSL certificate is soon to expire

final_endpoint
string

Specify where the redirect chain should end

find_string
string

String to look for within the response. Considered down if not found

follow_redirects
boolean

Whether to follow redirects when testing. Disabled by default

host
string

Name of the hosting provider

include_header
boolean

Include header content in string match search

paused
boolean

Whether the check should be run

port
integer <int32> >= 0

Destination port for TCP checks

post_body
string

JSON object. Payload submitted with the request. Setting this updates the check to use the HTTP POST verb

post_raw
string

Raw HTTP POST string to send to the server

regions
Array of strings

List of regions on which to run checks. The values required for this parameter can be retrieved from the GET /v1/uptime-locations endpoint.

status_codes_csv
string

Comma separated list of status codes that trigger an alert

tags
Array of strings

List of tags

timeout
integer <int32> [ 5 .. 75 ]

The number of seconds to wait to receive the first byte

trigger_rate
integer <int32> [ 0 .. 60 ]

The number of minutes to wait before sending an alert

use_jar
boolean

Whether to enable cookie storage

user_agent
string

Custom user agent string set when testing

Responses

Request samples

curl -X PUT https://api.statuscake.com/v1/uptime/123 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Example%20HTTP&check_rate=1800&regions[]=london&regions[]=paris"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

Delete an uptime check

Deletes an uptime check with the given id.

path Parameters
test_id
required
string

Uptime check ID

Responses

Request samples

curl -X DELETE https://api.statuscake.com/v1/uptime/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

Get all uptime check history

Returns a list of uptime check history results for a given id, detailing the runs performed on the StatusCake testing infrastruture.

The returned results are a paginated series. Alongside the response data is a links object referencing the current response document, self, and the next page in the series, next.

path Parameters
test_id
required
string

Uptime check ID

query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of results to return per page

before
integer <int64> >= 0

Only results created before this UNIX timestamp will be returned

after
integer <int64> >= 0

Only results created after this UNIX timestamp will be returned

Responses

Response Schema: application/json
required
Array of objects (UptimeTestHistoryResult)

List of uptime check history results

required
object (Links)
object (Metadata)

Request samples

curl https://api.statuscake.com/v1/uptime/123/history \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

Get all uptime check periods

Returns a list of uptime check periods for a given id, detailing the creation time of the period, when it ended and the duration.

The returned results are a paginated series. Alongside the response data is a links object referencing the current response document, self, and the next page in the series, next.

path Parameters
test_id
required
string

Uptime check ID

query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of uptime check periods to return per page

before
integer <int64> >= 0

Only check periods created before this UNIX timestamp will be returned

after
integer <int64> >= 0

Only check periods created after this UNIX timestamp will be returned

Responses

Response Schema: application/json
required
Array of objects (UptimeTestPeriod)

List of uptime check periods

required
object (Links)
object (Metadata)

Request samples

curl https://api.statuscake.com/v1/uptime/123/periods \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

Get all uptime check alerts

Returns a list of uptime check alerts for a given id.

The returned results are a paginated series. Alongside the response data is a links object referencing the current response document, self, and the next page in the series, next.

path Parameters
test_id
required
string

Uptime check ID

query Parameters
limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of uptime alerts to return per page

before
integer <int64> >= 0

Only alerts triggered before this UNIX timestamp will be returned

after
integer <int64> >= 0

Only alerts triggered after this UNIX timestamp will be returned

Responses

Response Schema: application/json
required
Array of objects (UptimeTestAlert)

List of uptime check alerts

required
object (Links)
object (Metadata)

Request samples

curl https://api.statuscake.com/v1/uptime/123/alerts \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

contact groups

The Contact Groups API provides methods to configure how StatusCake alerts are forwarded to the people that need to see them.

Get all contact groups

Returns a list of contact groups for an account.

query Parameters
page
integer <int32> >= 1
Default: 1

Page of results

limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of contact groups to return per page

Responses

Response Schema: application/json
required
Array of objects (ContactGroup)

List of contact groups

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/contact-groups \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

Create a contact group

Creates a contact group with the given parameters.

Request Body schema: application/x-www-form-urlencoded
name
required
string

Name of the contact group

email_addresses
Array of strings

List of email addresses

integrations
Array of strings

List of integration IDs

mobile_numbers
Array of strings

List of international format mobile phone numbers

ping_url
string <uri>

URL or IP address of an endpoint to push uptime events. Currently this only supports HTTP GET endpoints

Responses

Request samples

curl -X POST https://api.statuscake.com/v1/contact-groups \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Operations%20Team&email_addresses[][email protected]&email_addresses[][email protected]"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a contact group

Returns a contact group with the given id.

path Parameters
group_id
required
string

Contact group ID

Responses

Response Schema: application/json
required
object (ContactGroup)
id
required
string

Contact group ID

name
required
string

Name of the contact group

email_addresses
required
Array of strings

List of email addresses

integrations
required
Array of strings

List of configured integration IDs

mobile_numbers
required
Array of strings

List of international format mobile phone numbers

ping_url
string <uri>

URL or IP address of an endpoint to push uptime events. Currently this only supports HTTP GET endpoints

Request samples

curl -X POST https://api.statuscake.com/v1/contact-groups/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{}

Update a contact group

Updates a contact group with the given parameters.

path Parameters
group_id
required
string

Contact group ID

Request Body schema: application/x-www-form-urlencoded
name
string

Name of the contact group

email_addresses
Array of strings

List of email addresses

integrations
Array of strings

List of integration IDs

mobile_numbers
Array of strings

List of international format mobile phone numbers

ping_url
string <uri>

URL or IP address of an endpoint to push uptime events. Currently this only supports HTTP GET endpoints

Responses

Request samples

curl -X PUT https://api.statuscake.com/v1/contact-groups/123 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Operations%20Team&email_addresses[][email protected]&email_addresses[][email protected]"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

Delete a contact group

Deletes a contact group with the given id.

path Parameters
group_id
required
string

Contact group ID

Responses

Request samples

curl -X DELETE https://api.statuscake.com/v1/contact-groups/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

maintenance windows

The Maintenance Windows API provides methods to pause alerts from being sent for scheduled maintenance periods.

NOTE: the API endpoints concerned with maintenance windows will only work with accounts registed to use the newer version of maintenance windows. This version of maintenance windows is incompatible with the original version and all existing windows will require migrating to be further used. Presently a tool to automate the migration of maintenance windows is under development.

Get all maintenance windows

Returns a list of maintenance windows for an account.

query Parameters
page
integer <int32> >= 1
Default: 1

Page of results

limit
integer <int32> [ 1 .. 100 ]
Default: 25

The number of maintenance windows to return per page

state
string
Enum: "active" "paused" "pending"

Maintenance window state

Responses

Response Schema: application/json
required
Array of objects (MaintenanceWindow)

List of maintenance windows

required
object (Pagination)

Request samples

curl https://api.statuscake.com/v1/maintenance-windows \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}

Create a maintenance window

Creates a maintenance window with the given parameters.

Request Body schema: application/x-www-form-urlencoded
name
required
string

Name of the maintenance window

end_at
required
string <date-time>

End of the maintenance window (RFC3339 format)

repeat_interval
string (MaintenanceWindowRepeatInterval)
Enum: "never" "1d" "1w" "2w" "1m"

How often the maintenance window should occur

start_at
required
string <date-time>

Start of the maintenance window (RFC3339 format)

tags
Array of strings

List of tags used to include matching uptime checks in this maintenance window. At least one of tests and tags must be present in the request

tests
Array of strings

List of uptime check IDs explicitly included in this maintenance window. At least one of tests and tags must be present in the request

timezone
required
string

Standard timezone associated with this maintenance window

Responses

Request samples

curl -X POST https://api.statuscake.com/v1/maintenance-windows \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Weekends&start_at=2021-12-06T01:30:00Z&end_at=2021-07-11T06:00:00Z&repeat_interval=1w&tags[]=production&timezone=UTC"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a maintenance window

Returns a maintenance window with the given id.

path Parameters
window_id
required
string

Maintenance window ID

Responses

Response Schema: application/json
required
object (MaintenanceWindow)
id
required
string

Maintenance window ID

name
required
string

Name of the maintenance window

end_at
required
string <date-time>

End of the maintenance window (RFC3339 format)

repeat_interval
required
string (MaintenanceWindowRepeatInterval)
Enum: "never" "1d" "1w" "2w" "1m"

How often the maintenance window should occur

start_at
required
string <date-time>

Start of the maintenance window (RFC3339 format)

state
required
string (MaintenanceWindowState)
Enum: "active" "paused" "pending"

Maintenance window state

tags
required
Array of strings

List of tags used to include matching uptime checks in this maintenance window

tests
required
Array of strings

List of uptime check IDs explicitly included in this maintenance window

timezone
required
string

Standard timezone associated with this maintenance window

Request samples

curl https://api.statuscake.com/v1/maintenance-windows/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a maintenance window

Updates a maintenance window with the given parameters.

path Parameters
window_id
required
string

Maintenance window ID

Request Body schema: application/x-www-form-urlencoded
name
string

Name of the maintenance window

end_at
string <date-time>

End of the maintenance window (RFC3339 format)

repeat_interval
string (MaintenanceWindowRepeatInterval)
Enum: "never" "1d" "1w" "2w" "1m"

How often the maintenance window should occur

start_at
string <date-time>

Start of the maintenance window (RFC3339 format)

tags
Array of strings

List of tags used to include matching uptime checks in this maintenance window

tests
Array of strings

List of uptime check IDs explicitly included in this maintenance window

timezone
string

Standard timezone associated with this maintenance window

Responses

Request samples

curl -X PUT https://api.statuscake.com/v1/maintenance-windows/123 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "name=Weekends&start_at=2021-12-06T01:30:00Z&end_at=2021-07-11T06:00:00Z&repeat_interval=1w&tags[]=production&timezone=UTC"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

Delete a maintenance window

Deletes a maintenance window with the given id.

path Parameters
window_id
required
string

Maintenance window ID

Responses

Request samples

curl -X DELETE https://api.statuscake.com/v1/maintenance-windows/123 \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "message": "Something went wrong",
  • "errors": {
    }
}

locations

The Locations API returns details of our testing infrastructure. This may be used to gather information regarding IP addresses that may need to be allowed through firewalls for checks to be succesful.

Get all uptime monitoring locations

Returns a list of locations detailing server information for uptime monitoring servers. This information can be used to create further checks using the API.

query Parameters
region_code
string

Server region code

Responses

Response Schema: application/json
required
Array of objects (MonitoringLocation)

List of monitoring locations

Array
description
required
string

Server description

ipv4
string <ipv4>

Server IPv4 address

ipv6
string <ipv6>

Server IPv6 address

region
required
string

Server region

region_code
required
string

Server region code

status
required
string (MonitoringLocationStatus)
Enum: "down" "up"

Server status

Request samples

curl https://api.statuscake.com/v1/uptime-locations \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get all pagespeed monitoring locations

Returns a list of locations detailing server information for pagespeed monitoring servers. This information can be used to create further checks using the API.

query Parameters
location
string

Alpha-2 ISO 3166-1 country code

Responses

Response Schema: application/json
required
Array of objects (MonitoringLocation)

List of monitoring locations

Array
description
required
string

Server description

ipv4
string <ipv4>

Server IPv4 address

ipv6
string <ipv6>

Server IPv6 address

region
required
string

Server region

region_code
required
string

Server region code

status
required
string (MonitoringLocationStatus)
Enum: "down" "up"

Server status

Request samples

curl https://api.statuscake.com/v1/pagespeed-locations \
  -H "Authorization: Bearer ${API_TOKEN}"

Response samples

Content type
application/json
{
  • "data": [
    ]
}