Reference

py_healthchecks.io

Py Healthchecks.Io.

class healthchecks_io.AsyncClient(api_key='', ping_key='', api_url='https://healthchecks.io/api/', ping_url='https://hc-ping.com/', api_version=1, client=None)

A Healthchecks.io client implemented using httpx’s Async methods.

Parameters:

  • api_key (str)

  • ping_key (str)

  • api_url (str)

  • ping_url (str)

  • api_version (int)

  • client (AsyncClient | None)

async create_check(new_check)

Creates a new check and returns it.

With this API call, you can create both Simple and Cron checks: * To create a Simple check, specify the timeout parameter. * To create a Cron check, specify the schedule and tz parameters.

Parameters:

new_check (CheckCreate) – New check you are wanting to create

Returns:

check that was just created

Return type:

Check

async delete_check(check_id)

Permanently deletes the check from the user’s account.

check_id must be a uuid, not a unique id

Parameters:

check_id (str) – check’s uuid

Returns:

the check just deleted

Return type:

Check

Raises:
async exit_code_ping(exit_code, uuid='', slug='', data='')

Signals to Healthchecks.io that the job has failed.

Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.

Can take a uuid or a slug. If you call with a slug, you much have a ping key set.

Check’s slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, Healthchecks.io will return the “409 Conflict” HTTP status code and ignore the request.

Parameters:

  • exit_code (int) – Exit code to sent, int from 0 to 255

  • uuid (str) – Check’s UUID. Defaults to “”.

  • slug (str) – Check’s Slug. Defaults to “”.

  • data (str) – Text data to append to this check. Defaults to “”.

Raises:

  • HCAPIAuthError – Raised when status_code == 401 or 403

  • HCAPIError – Raised when status_code is 5xx

  • CheckNotFoundError – Raised when status_code is 404 or response text has “not found” in it

  • BadAPIRequestError – Raised when status_code is 400, or if you pass a uuid and a slug, or if pinging by a slug and do not have a ping key set

  • HCAPIRateLimitError – Raised when status code is 429 or response text has “rate limited” in it

  • NonUniqueSlugError – Raused when status code is 409.

Returns:

success (true or false) and the response text

Return type:

Tuple[bool, str]

async fail_ping(uuid='', slug='', data='')

Signals to Healthchecks.io that the job has failed.

Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.

Can take a uuid or a slug. If you call with a slug, you much have a ping key set.

Check’s slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, Healthchecks.io will return the “409 Conflict” HTTP status code and ignore the request.

Parameters:

  • uuid (str) – Check’s UUID. Defaults to “”.

  • slug (str) – Check’s Slug. Defaults to “”.

  • data (str) – Text data to append to this check. Defaults to “”.

Raises:

  • HCAPIAuthError – Raised when status_code == 401 or 403

  • HCAPIError – Raised when status_code is 5xx

  • CheckNotFoundError – Raised when status_code is 404 or response text has “not found” in it

  • BadAPIRequestError – Raised when status_code is 400, or if you pass a uuid and a slug, or if pinging by a slug and do not have a ping key set

  • HCAPIRateLimitError – Raised when status code is 429 or response text has “rate limited” in it

  • NonUniqueSlugError – Raused when status code is 409.

Returns:

success (true or false) and the response text

Return type:

Tuple[bool, str]

async get_badges()

Returns a dict of all tags in the project, with badge URLs for each tag.

Healthchecks.io provides badges in a few different formats: svg: returns the badge as a SVG document. json: returns a JSON document which you can use to generate a custom badge yourself. shields: returns JSON in a Shields.io compatible format. In addition, badges have 2-state and 3-state variations:

svg, json, shields: reports two states: “up” and “down”. It considers any checks in the grace period as still “up”. svg3, json3, shields3: reports three states: “up”, “late”, and “down”.

The response includes a special * entry: this pseudo-tag reports the overal status of all checks in the project.

Raises:
Returns:

Dictionary of all tags in the project with badges

Return type:

Dict[str, Badges]

async get_check(check_id)

Get a single check by id.

check_id can either be a check uuid if using a read/write api key or a unique key if using a read only api key.

Parameters:

check_id (str) – check’s uuid or unique id

Returns:

the check

Return type:

Check

Raises:
async get_check_flips(check_id, seconds=None, start=None, end=None)

Returns a list of “flips” this check has experienced.

A flip is a change of status (from “down” to “up,” or from “up” to “down”).

Raises:
Parameters:

  • check_id (str) – check uuid

  • seconds (Optional[int], optional) – Returns the flips from the last value seconds. Defaults to None.

  • start (Optional[int], optional) – Returns flips that are newer than the specified UNIX timestamp. Defaults to None.

  • end (Optional[int], optional) – Returns flips that are older than the specified UNIX timestamp. Defaults to None.

Returns:

List of status flips for this check

Return type:

List[CheckStatuses]

async get_check_pings(check_id)

Returns a list of pings this check has received.

This endpoint returns pings in reverse order (most recent first), and the total number of returned pings depends on the account’s billing plan: 100 for free accounts, 1000 for paid accounts.

Parameters:

check_id (str) – check’s uuid

Returns:

list of pings this check has received

Return type:

List[CheckPings]

Raises:
async get_checks(tags=None)

Get a list of checks from the healthchecks api.

Parameters:

tags (Optional[List[str]], optional) – Filters the checks and returns only the checks that are tagged with the specified value. Defaults to None.

Raises:
Returns:

[description]

Return type:

List[Check]

async get_integrations()

Returns a list of integrations belonging to the project.

Raises:
Returns:

List of integrations for the project

Return type:

List[Optional[Integration]]

async pause_check(check_id)

Disables monitoring for a check without removing it.

The check goes into a “paused” state. You can resume monitoring of the check by pinging it.

check_id must be a uuid, not a unique id

Parameters:

check_id (str) – check’s uuid

Returns:

the check just paused

Return type:

Check

Raises:
async start_ping(uuid='', slug='', data='')

Sends a “job has started!” message to Healthchecks.io.

Sending a “start” signal is optional, but it enables a few extra features: * Healthchecks.io will measure and display job execution times * Healthchecks.io will detect if the job runs longer than its configured grace time

Can take a uuid or a slug. If you call with a slug, you much have a ping key set.

Check’s slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, Healthchecks.io will return the “409 Conflict” HTTP status code and ignore the request.

Parameters:

  • uuid (str) – Check’s UUID. Defaults to “”.

  • slug (str) – Check’s Slug. Defaults to “”.

  • data (str) – Text data to append to this check. Defaults to “”.

Raises:

  • HCAPIAuthError – Raised when status_code == 401 or 403

  • HCAPIError – Raised when status_code is 5xx

  • CheckNotFoundError – Raised when status_code is 404 or response text has “not found” in it

  • BadAPIRequestError – Raised when status_code is 400, or if you pass a uuid and a slug, or if pinging by a slug and do not have a ping key set

  • HCAPIRateLimitError – Raised when status code is 429 or response text has “rate limited” in it

  • NonUniqueSlugError – Raused when status code is 409.

Returns:

success (true or false) and the response text

Return type:

Tuple[bool, str]

async success_ping(uuid='', slug='', data='')

Signals to Healthchecks.io that a job has completed successfully.

Can also be used to indicate a continuously running process is still running and healthy.

Can take a uuid or a slug. If you call with a slug, you much have a ping key set.

Check’s slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, Healthchecks.io will return the “409 Conflict” HTTP status code and ignore the request.

Parameters:

  • uuid (str) – Check’s UUID. Defaults to “”.

  • slug (str) – Check’s Slug. Defaults to “”.

  • data (str) – Text data to append to this check. Defaults to “”.

Raises:

  • HCAPIAuthError – Raised when status_code == 401 or 403

  • HCAPIError – Raised when status_code is 5xx

  • CheckNotFoundError – Raised when status_code is 404 or response text has “not found” in it

  • BadAPIRequestError – Raised when status_code is 400, or if you pass a uuid and a slug, or if pinging by a slug and do not have a ping key set

  • HCAPIRateLimitError – Raised when status code is 429 or response text has “rate limited” in it

  • NonUniqueSlugError – Raused when status code is 409.

Returns:

success (true or false) and the response text

Return type:

Tuple[bool, str]

async update_check(uuid, update_check)

Updates an existing check.

If you omit any parameter in update_check, Healthchecks.io will leave its value unchanged.

Parameters:

  • uuid (str) – UUID for the check to update

  • update_check (CheckCreate) – Check values you want to update

Returns:

check that was just updated

Return type:

Check

exception healthchecks_io.BadAPIRequestError

Thrown when an api request returns a 400.

class healthchecks_io.Badges(*, svg, svg3, json_url, json3_url, shields, shields3)

Object with the Badges urls.

Parameters:

  • svg (str)

  • svg3 (str)

  • json_url (str)

  • json3_url (str)

  • shields (str)

  • shields3 (str)

classmethod from_api_result(badges_dict)

Converts a dictionary from the healthchecks api into a Badges object.

Parameters:

badges_dict (Dict[str, str])

Return type:

Badges

class healthchecks_io.Check(*, unique_key=None, name, slug, tags=None, desc=None, grace, n_pings, status, last_ping=None, next_ping=None, manual_resume, methods=None, ping_url=None, update_url=None, pause_url=None, channels=None, timeout=None, uuid=None)

Schema for a check object, either from a readonly api request or a rw api request.

Parameters:

  • unique_key (str | None)

  • name (str)

  • slug (str)

  • tags (str | None)

  • desc (str | None)

  • grace (int)

  • n_pings (int)

  • status (str)

  • last_ping (datetime | None)

  • next_ping (datetime | None)

  • manual_resume (bool)

  • methods (str | None)

  • ping_url (str | None)

  • update_url (str | None)

  • pause_url (str | None)

  • channels (str | None)

  • timeout (int | None)

  • uuid (str | None)

classmethod from_api_result(check_dict)

Converts a dictionary from the healthchecks api into an Check object.

Parameters:

check_dict (Dict[str, Any])

Return type:

Check

classmethod validate_uuid(value, values)

Tries to set the uuid from the ping_url.

Will return none if a read only token is used because it cannot retrieve the UUID of a check

Parameters:

  • value (str | None)

  • values (Dict[str, Any])

Return type:

str | None

class healthchecks_io.CheckCreate(*, name='', tags='', desc='', timeout=86400, grace=3600, schedule=None, tz='UTC', manual_resume=False, methods='', channels=None, unique=[])

Pydantic object for creating a check.

Parameters:

  • name (str | None)

  • tags (str | None)

  • desc (str | None)

  • timeout (int | None)

  • grace (int | None)

  • schedule (str | None)

  • tz (str | None)

  • manual_resume (bool | None)

  • methods (str | None)

  • channels (str | None)

  • unique (List[str | None] | None)

classmethod validate_methods(value)

Validate that methods.

Parameters:

value (str)

Return type:

str

classmethod validate_schedule(value)

Validates that the schedule is a valid cron expression.

Parameters:

value (str)

Return type:

str

classmethod validate_tz(value)

Validates that the timezone is a valid timezone string.

Parameters:

value (str)

Return type:

str

classmethod validate_unique(value)

Validate unique list.

Parameters:

value (List[str | None])

Return type:

List[str | None]

exception healthchecks_io.CheckNotFoundError

Thrown when getting a check returns a 404.

class healthchecks_io.CheckPings(*, type, date, number_of_pings, scheme, remote_addr, method, user_agent, duration=None)

A Pydantic schema for a check’s Pings.

Parameters:

  • type (str)

  • date (datetime)

  • number_of_pings (int)

  • scheme (str)

  • remote_addr (str)

  • method (str)

  • user_agent (str)

  • duration (float | None)

classmethod from_api_result(ping_dict)

Converts a dictionary from the healthchecks api into a CheckPings object.

Parameters:

ping_dict (Dict[str, str | int | datetime])

Return type:

CheckPings

class healthchecks_io.CheckStatuses(*, timestamp, up)

A Pydantic schema for a check’s Statuses.

Parameters:

  • timestamp (datetime)

  • up (int)

class healthchecks_io.CheckTrap(client, uuid='', slug='', suppress_exceptions=False)

CheckTrap is a context manager to wrap around python code to communicate results to a Healthchecks check.

Parameters:
add_log(line)

Add a line to the context manager’s log that is sent with the check.

Parameters:

line (str) – String to add to the logs

Return type:

None

class healthchecks_io.CheckUpdate(*, name=None, tags=None, desc='', timeout=None, grace=None, schedule=None, tz=None, manual_resume=None, methods=None, channels=None, unique=None)

Pydantic object for updating a check.

Parameters:

  • name (str | None)

  • tags (str | None)

  • desc (str | None)

  • timeout (int | None)

  • grace (int | None)

  • schedule (str | None)

  • tz (str | None)

  • manual_resume (bool | None)

  • methods (str | None)

  • channels (str | None)

  • unique (List[str | None] | None)

class healthchecks_io.Client(api_key='', ping_key='', api_url='https://healthchecks.io/api/', ping_url='https://hc-ping.com/', api_version=1, client=None)

A Healthchecks.io client implemented using httpx’s sync methods.

Parameters:

  • api_key (str)

  • ping_key (str)

  • api_url (str)

  • ping_url (str)

  • api_version (int)

  • client (Client | None)

create_check(new_check)

Creates a new check and returns it.

With this API call, you can create both Simple and Cron checks: * To create a Simple check, specify the timeout parameter. * To create a Cron check, specify the schedule and tz parameters.

Parameters:

new_check (CheckCreate) – New check you are wanting to create

Returns:

check that was just created

Return type:

Check

delete_check(check_id)

Permanently deletes the check from the user’s account.

check_id must be a uuid, not a unique id

Parameters:

check_id (str) – check’s uuid

Returns:

the check just deleted

Return type:

checks.Check

Raises:
exit_code_ping(exit_code, uuid='', slug='', data='')

Signals to Healthchecks.io that the job has failed.

Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.

Can take a uuid or a slug. If you call with a slug, you much have a ping key set.

Check’s slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, Healthchecks.io will return the “409 Conflict” HTTP status code and ignore the request.

Parameters:

  • exit_code (int) – Exit code to sent, int from 0 to 255

  • uuid (str) – Check’s UUID. Defaults to “”.

  • slug (str) – Check’s Slug. Defaults to “”.

  • data (str) – Text data to append to this check. Defaults to “”

Raises:

  • HCAPIAuthError – Raised when status_code == 401 or 403

  • HCAPIError – Raised when status_code is 5xx

  • CheckNotFoundError – Raised when status_code is 404 or response text has “not found” in it

  • BadAPIRequestError – Raised when status_code is 400, or if you pass a uuid and a slug, or if pinging by a slug and do not have a ping key set

  • HCAPIRateLimitError – Raised when status code is 429 or response text has “rate limited” in it

  • NonUniqueSlugError – Raused when status code is 409.

Returns:

success (true or false) and the response text

Return type:

Tuple[bool, str]

fail_ping(uuid='', slug='', data='')

Signals to Healthchecks.io that the job has failed.

Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.

Can take a uuid or a slug. If you call with a slug, you much have a ping key set.

Check’s slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, Healthchecks.io will return the “409 Conflict” HTTP status code and ignore the request.

Parameters:

  • uuid (str) – Check’s UUID. Defaults to “”.

  • slug (str) – Check’s Slug. Defaults to “”.

  • data (str) – Text data to append to this check. Defaults to “”

Raises:

  • HCAPIAuthError – Raised when status_code == 401 or 403

  • HCAPIError – Raised when status_code is 5xx

  • CheckNotFoundError – Raised when status_code is 404 or response text has “not found” in it

  • BadAPIRequestError – Raised when status_code is 400, or if you pass a uuid and a slug, or if pinging by a slug and do not have a ping key set

  • HCAPIRateLimitError – Raised when status code is 429 or response text has “rate limited” in it

  • NonUniqueSlugError – Raused when status code is 409.

Returns:

success (true or false) and the response text

Return type:

Tuple[bool, str]

get_badges()

Returns a dict of all tags in the project, with badge URLs for each tag.

Healthchecks.io provides badges in a few different formats: svg: returns the badge as a SVG document. json: returns a JSON document which you can use to generate a custom badge yourself. shields: returns JSON in a Shields.io compatible format. In addition, badges have 2-state and 3-state variations:

svg, json, shields: reports two states: “up” and “down”. It considers any checks in the grace period

as still “up”.

svg3, json3, shields3: reports three states: “up”, “late”, and “down”.

The response includes a special * entry: this pseudo-tag reports the overal status of all checks in the project.

Raises:
Returns:

Dictionary of all tags in the project with badges

Return type:

Dict[str, badges.Badges]

get_check(check_id)

Get a single check by id.

check_id can either be a check uuid if using a read/write api key or a unique key if using a read only api key.

Parameters:

check_id (str) – check’s uuid or unique id

Returns:

the check

Return type:

checks.Check

Raises:
get_check_flips(check_id, seconds=None, start=None, end=None)

Returns a list of “flips” this check has experienced.

A flip is a change of status (from “down” to “up,” or from “up” to “down”).

Raises:
Parameters:

  • check_id (str) – check uuid

  • seconds (Optional[int], optional) – Returns the flips from the last value seconds. Defaults to None.

  • start (Optional[int], optional) – Returns flips that are newer than the specified UNIX timestamp. Defaults to None.

  • end (Optional[int], optional) – Returns flips that are older than the specified UNIX timestamp. Defaults to None.

Returns:

List of status flips for this check

Return type:

List[checks.CheckStatuses]

get_check_pings(check_id)

Returns a list of pings this check has received.

This endpoint returns pings in reverse order (most recent first), and the total number of returned pings depends on the account’s billing plan: 100 for free accounts, 1000 for paid accounts.

Parameters:

check_id (str) – check’s uuid

Returns:

list of pings this check has received

Return type:

List[checks.CheckPings]

Raises:
get_checks(tags=None)

Get a list of checks from the healthchecks api.

Parameters:

tags (Optional[List[str]], optional) – Filters the checks and returns only the checks that are tagged with the specified value. Defaults to None.

Raises:

  • HCAPIAuthError – When the API returns a 401, indicates an api key issue

  • HCAPIError – When the API returns anything other than a 200 or 401

Returns:

[description]

Return type:

List[checks.Check]

get_integrations()

Returns a list of integrations belonging to the project.

Raises:
Returns:

List of integrations for the project

Return type:

List[Optional[integrations.Integration]]

pause_check(check_id)

Disables monitoring for a check without removing it.

The check goes into a “paused” state. You can resume monitoring of the check by pinging it.

check_id must be a uuid, not a unique id

Parameters:

check_id (str) – check’s uuid

Returns:

the check just paused

Return type:

checks.Check

Raises:
start_ping(uuid='', slug='', data='')

Sends a “job has started!” message to Healthchecks.io.

Sending a “start” signal is optional, but it enables a few extra features: * Healthchecks.io will measure and display job execution times * Healthchecks.io will detect if the job runs longer than its configured grace time

Can take a uuid or a slug. If you call with a slug, you much have a ping key set.

Check’s slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, Healthchecks.io will return the “409 Conflict” HTTP status code and ignore the request.

Parameters:

  • uuid (str) – Check’s UUID. Defaults to “”.

  • slug (str) – Check’s Slug. Defaults to “”.

  • data (str) – Text data to append to this check. Defaults to “”

Raises:

  • HCAPIAuthError – Raised when status_code == 401 or 403

  • HCAPIError – Raised when status_code is 5xx

  • CheckNotFoundError – Raised when status_code is 404 or response text has “not found” in it

  • BadAPIRequestError – Raised when status_code is 400, or if you pass a uuid and a slug, or if pinging by a slug and do not have a ping key set

  • HCAPIRateLimitError – Raised when status code is 429 or response text has “rate limited” in it

  • NonUniqueSlugError – Raused when status code is 409.

Returns:

success (true or false) and the response text

Return type:

Tuple[bool, str]

success_ping(uuid='', slug='', data='')

Signals to Healthchecks.io that a job has completed successfully.

Can also be used to indicate a continuously running process is still running and healthy.

Can take a uuid or a slug. If you call with a slug, you much have a ping key set.

Check’s slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, Healthchecks.io will return the “409 Conflict” HTTP status code and ignore the request.

Parameters:

  • uuid (str) – Check’s UUID. Defaults to “”.

  • slug (str) – Check’s Slug. Defaults to “”.

  • data (str) – Text data to append to this check. Defaults to “”

Raises:

  • HCAPIAuthError – Raised when status_code == 401 or 403

  • HCAPIError – Raised when status_code is 5xx

  • CheckNotFoundError – Raised when status_code is 404 or response text has “not found” in it

  • BadAPIRequestError – Raised when status_code is 400, or if you pass a uuid and a slug, or if pinging by a slug and do not have a ping key set

  • HCAPIRateLimitError – Raised when status code is 429 or response text has “rate limited” in it

  • NonUniqueSlugError – Raused when status code is 409.

Returns:

success (true or false) and the response text

Return type:

Tuple[bool, str]

update_check(uuid, update_check)

Updates an existing check.

If you omit any parameter in update_check, Healthchecks.io will leave its value unchanged.

With this API call, you can create both Simple and Cron checks: * To create a Simple check, specify the timeout parameter. * To create a Cron check, specify the schedule and tz parameters.

Parameters:

  • uuid (str) – UUID for the check to update

  • update_check (CheckCreate) – Check values you want to update

Returns:

check that was just updated

Return type:

Check

exception healthchecks_io.HCAPIAuthError

Thrown when we fail to auth to the Healthchecks api.

exception healthchecks_io.HCAPIError

API Exception for when we have an error with the healthchecks api.

exception healthchecks_io.HCAPIRateLimitError

Thrown when the api returns a rate limit response.

class healthchecks_io.Integration(*, id, name, kind)

Schema for an integration object.

Parameters:

  • id (str)

  • name (str)

  • kind (str)

classmethod from_api_result(integration_dict)

Converts a dictionary from the healthchecks api into an Integration object.

Parameters:

integration_dict (Dict[str, str])

Return type:

Integration

exception healthchecks_io.NonUniqueSlugError

Thrown when the api returns a 409 when pinging.

exception healthchecks_io.PingFailedError

Thrown when a ping fails.

exception healthchecks_io.WrongClientError

Thrown when trying to use a CheckTrap with the wrong client type.