API Documentation | Data

The data extraction API is a (beta) read only endpoint to pull the values of a single data point for a given time range.


_cid string
The primary key
A string containing a data cid
data array
The data stored in circonus for the requested
An array
string (zero or more times)
The data that Circonus has stored for the time period
One or more data structures as defined in the examples


Extracting Data

The data endpoint provides a simple way to extact data from Circonus. Please note that this is a BETA API endpoint, and is subject to change without notice.

To extract data you need perform a HTTP GET request on the data cid. This follows the format "/data/[check_id]_[metric_name]".

You must also provide the following parameters:

The type of data you wish to extract. This must be text, numeric, or histogram
The start time, in epoch seconds, of the duration you wish to export data from
The end time, in epoch seconds, of the duration you wish to export data from
For numeric and histogram types only, and not text. The resolution of data you want to get back (in seconds), valid values are: 60, 300, 1800, 10800, and 86400.

Extracting Numeric Metric Data

Numeric data uses objects to return the compiled statistics for the various datapoints:

For numeric data you may also optionally provide the following fields to format your output:

The format of the data you wish to extract. This can be:
  • legacy - original format where each record is [<timestamp>, <object of values>] (see example below)
  • tuple - where each record is a JSON array of just numeric value fields with no field identifiers
  • object - where each record is a JSON object with field identifier.
When format is not legacy this will control which fields come back in the output and their order. Valid fields are listed under the first example below.

legacy Format

GET /data/1234_cpu?type=numeric&start=1362400895&end=1362487307&period=300

tuple Format

GET /data/1234_cpu?type=numeric&start=1362400895&end=1362487307&period=300&format=tuple&format_fields=timestamp,value

object Format

GET /data/1234_cpu?type=numeric&start=1362400895&end=1362487307&period=300&format=object&format_fields=timestamp,value

Extracting Histogram Metric Data

Histogram data uses objects to return the histogram information. The keys of the object are stringified numbers that represent the lower-bound of a bucket where the upper range is the next value expressible in base 10 with two digits of precision. (e.g "0.12" expresses [0.12,0.13) and "990" expresses [990, 1000))

GET /data/1235_pingtime?type=histogram&start=1362400895&end=1362487307&period=300
{"_cid":"1235_pingtime","data":[["<timestamp>","<period>",{"<bucket1>":"<count of items in bucket1>","<bucket2>":"<count of items in bucket2>"}],"\u2026"]}

Extracting Text Metric Data

Text data can be extracted in a similar way, but you do not pass the period parameter. The returned data structure only contains entries where the data changes

GET /data/1236_ip?type=text&start=1362400895&end=1362487307
{"data":[["<timestamp>","<new value>"],"\u2026"],"_cid":"/data/1236_ip"}