Aggregates API

The /aggregates API endpoint

The /aggregates API endpoint provides HTTP GET access to named aggregate data.

/aggregates (GET)

EXAMPLES

The following example demonstrates a /aggregates API query which results in a JSON Array of JSON Hashes containing named check aggregates.

$ curl -s http://127.0.0.1:3000/aggregates | jq .
[
  {
    "_id": "us_east1/check_web_app",
    "dc": "us_east1",
    "name": "check_web_app"
  },
  {
    "_id": "us_west1/elasticsearch_health",
    "dc": "us_west1",
    "name": "elasticsearch_health"
  }
]

API specification

/aggregates (GET)
description Returns the list of named aggregates by name and datacenter (dc)
example url http://hostname:3000/aggregates
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "_id": "us_east1/check_web_app",
    "dc": "us_east1",
    "name": "check_web_app"
  },
  {
    "_id": "us_west1/elasticsearch_health",
    "dc": "us_west1",
    "name": "elasticsearch_health"
  }
]

The /aggregates/:name API endpoints

The /aggregates/:name API endpoints provide HTTP GET and HTTP DELETE access to check aggregate data for a named aggregate.

/aggregates/:name (GET)

EXAMPLES

The following example demonstrates a /aggregates/:name API query for the check result data for the aggregate named example_aggregate.

$ curl -s http://127.0.0.1:3000/aggregates/example_aggregate | jq .
{
  "clients": 15,
  "checks": 2,
  "results": {
    "ok": 18,
    "warning": 0,
    "critical": 1,
    "unknown": 0,
    "total": 19,
    "stale": 0
  }
}

API specification

/aggregates/:name (GET)
description Returns the aggregate check result for a given aggregate.
example url http://hostname:3000/aggregates/elasticsearch
parameters
  • dc:
    • required: false
    • type: String
    • description: If the aggregate name is present in multiple datacenters, specifying the dc parameter returns only the aggregate found in that datacenter.
    • example: http://hostname:3000/aggregates/elasticsearch?dc=us_west1
response type Array
response codes
  • Success: 200 (OK)
  • Found in multiple datacenters: 300 (Multiple Choices)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
{
  "clients": 15,
  "checks": 2,
  "results": {
    "ok": 18,
    "warning": 0,
    "critical": 1,
    "unknown": 0,
    "total": 19,
    "stale": 0
  }
}

/aggregates/:name (DELETE)

EXAMPLES

The following example demonstrates a /aggregates/:name API request to delete aggregate data for the aggregate named example_aggregate.

$ curl -s -i -X DELETE http://127.0.0.1:3000/aggregates/example_aggregate
HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Connection: close
Server: thin

API specification

/aggregates/:name (DELETE)
description Deletes all aggregate data for a named aggregate.
example url http://hostname:3000/aggregates/elasticsearch
parameters
  • dc:
    • required: false
    • type: String
    • description: If the aggregate name is present in multiple datacenters, specifying the dc parameter accesses only the aggregate found in that datacenter.
    • example: http://hostname:3000/aggregates/elasticsearch?dc=us_west1
response type HTTP-header only (no output)
response codes
  • Success: 202 (Accepted)
  • Found in multiple datacenters: 300 (Multiple Choices)
  • Missing: 404 (Not Found)
  • Error: 500 (Internal Server Error)
output 
HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Connection: close
Server: thin