API Documentation | Check

Checks are the individual elements of a check bundle. They consist of a configuration running on a specific broker. Checks are read only, to make a change to one you must change to all the checks in a bundle, so any modifications should be done to the check_bundle endpoint.

Fields

_cid string
The primary key
"/check/23954"
A string containing a check cid
_active boolean
Is this check currently active and collecting data.
true
Either true or false
_broker string
The ID of the broker that runs this check.
"/broker/1"
A string containing a broker cid
_check_bundle string
The ID of the bundle this check belongs to.
"/check_bundle/21388"
A string containing a check_bundle cid
_check_uuid string
The UUID that universally identifies this check.
A string containing freeform text
_details object
A listing of possible check specific details. This is likely to be empty for most checks.
{}
An object
_reverse_url string
Reverse url
A string containing freeform text

Example

Fetching Checks

Fetching details for a check is as simple as peforming a GET on the check cid:

GET /check/12345
{"_cid":"/check/23954","_check_uuid":"25b5a748-5614-44f1-87e3-32ca709c9c45","_active":true,"_check_bundle":"/check_bundle/21388","_details":{},"_broker":"/broker/1"}

We can see that this check gathers the metrics defined in /check_bundle/21388 from broker /broker/1 (if that check bundle gathers the metrics a second time from another broker Circonus will create a second check for that.)

Creating, Updating and Removing Checks

It is not possible to directly modify a check using the /check paths. Instead you should modify the check bundle that created the check; Checks are created and removed automatically by Circonus as necessary to support the monitoring the metrics from the required brokers.

Listing and Filtering Checks

All checks for an account can be listed simply by performing a HTTP GET request on /check:

GET /check
[{"_cid":"/check/62513","_check_uuid":"783fec52-9a57-437d-b53c-f1f11043bfea","_active":true,"_check_bundle":"/check_bundle/45315","_details":{},"_broker":"/broker/2"},{"_cid":"/check/11641","_check_uuid":"2f3f5c52-3857-a37d-a53c-f1f11043bbfb","_active":true,"_check_bundle":"/check_bundle/9546","_details":{},"_broker":"/broker/32"},"\u2026",{"_broker":"/broker/32","_check_bundle":"/check_bundle/45315","_details":{},"_active":true,"_check_uuid":"8f3fec52-2a57-327d-a53c-f1f11043aff2","_cid":"/check/62515"},{"_check_bundle":"/check_bundle/14989","_details":{},"_broker":"/broker/32","_active":true,"_cid":"/check/17277","_check_uuid":"5f3fec52-9a57-437d-a53c-f1f11043bffc"},{"_cid":"/check/23952","_check_uuid":"523fec52-9a57-737d-a53c-f1f11043bf6b","_check_bundle":"/check_bundle/21387","_details":{},"_broker":"/broker/32","_active":true},{"_check_bundle":"/check_bundle/9547","_details":{},"_broker":"/broker/32","_active":true,"_cid":"/check/11642","_check_uuid":"2f3fec52-9a57-437d-a53c-f1f11043bf22"},{"_cid":"/check/11643","_check_uuid":"8f3fec52-9a57-127d-a53c-f1f11043bc2b","_details":{},"_check_bundle":"/check_bundle/9548","_broker":"/broker/1","_active":true},{"_check_uuid":"143fec52-9a57-567d-a53c-f1f11043bffb","_cid":"/check/62514","_broker":"/broker/1","_details":{},"_check_bundle":"/check_bundle/45315","_active":true},{"_cid":"/check/23953","_check_uuid":"893fec52-9a57-237d-a53c-f1f11043bf33","_details":{},"_check_bundle":"/check_bundle/21387","_broker":"/broker/1","_active":true},{"_cid":"/check/23954","_check_uuid":"ac3fec52-9a57-488d-a53c-f1f11043bf2c","_check_bundle":"/check_bundle/21388","_details":{},"_broker":"/broker/1","_active":true},{"_broker":"/broker/1","_details":{},"_check_bundle":"/check_bundle/45316","_active":true,"_check_uuid":"ca3fec52-9a57-ac7d-a53c-f1f11043bf28","_cid":"/check/62516"}]

Checks can be filtered in the standard way, for example to only list those checks that exist on broker /broker/2 and are part of check bundle /check_bundle/45315:

Note on filtering, you should not use a filter without a search parameter as well, using just a filter may become unsupported in the future. Please see the section on API searching.

GET /check?search=(check_bundle_id%3A45315)&f__broker=/broker/2
[{"_active":true,"_check_bundle":"/check_bundle/45315","_details":{},"_broker":"/broker/2","_cid":"/check/62513","_check_uuid":"783fec52-9a57-437d-b53c-f1f11043bfea"}]