Axibase Time Series Database

Series: get

Description

Retrieves series values for the specified entity, metric, and series tags in JSON or CSV format.

The method implements a subset of features of the Series: Query method with a simplified parameter syntax.

Request

Method Path
GET /api/v1/series/{format}/{entity}/{metric}

Path Parameters

Name Description
entity [Required] Entity name.
metric [Required] Metric name.
format [Required] Response format: csv or json.

Query String Parameters

Date Parameters

The date interval for loading the time series is required and must be defined using a combination of any of the two parameters listed below. Refer to date filter for more details.

Name Type Description
startDate string Start date in ISO format or calendar expression.
endDate string End date in ISO format or calendar expression.
interval string Interval specified as count-time_unit.
Example: interval=1-DAY.
Refer to the list of supported time units.

Examples:

  • interval=1-DAY&endDate=now
  • startDate=2018-01-01T00:00:00Z&endDate=2018-06-01T00:00:00Z
  • startDate=previous_month&endDate=current_month

Series Filter Parameters

To restrict results to series with specific tags, specify one or multiple tag names and values in the query string. A series is included in the results if it contains all of the requested tags and the tag values match the values enumerated in the request.

Name Type Description
t:{name} string Series tag name and value.
Prefix the tag name by t: to differentiate it from other parameters.
Example: t:disk=sda1.
Example: t:disk=sda1&t:fstype=ext4.
Multiple values for the same tag can be requested by repeating the parameter.
Example: t:disk=sda1&t:disk=sdb1.
Tag value supports wildcards, for example t:disk=*.

Aggregation Parameters

Name Type Description
aggregate string Statistical function applied to detailed values in each period.
Example: aggregate=avg.
period string Duration of the aggregation period specified as count-time_unit.
Example: period=1-HOUR.
Refer to the list of supported time units.
align string Alignment of the period start or end time.
Allowed values: CALENDAR, START_TIME, END_TIME, FIRST_VALUE_TIME.
Default: CALENDAR.
Example: align=START_TIME. Refer to the alignment for more details.

Format Parameters

Name Type Description
limit integer Limit the response to last N samples for each series.
The constraint applies to each series in the response separately.
Default: 0 (unlimited).
Example: limit=1.
fields string Applies to CSV format.
Columns included in the response.
Possible values: time, date, entity, metric, value, requested tag names (prefixed by t:).
Default: time, entity, metric, requested tag names, value.
Example: columns=time,t:disk,value.
timeFormat string Applies to JSON format.
Timestamp format in the data array in the JSON document.
Possible values: iso, milliseconds. Default: milliseconds.
Example: timeFormat=iso.

Response

JSON Format

The returned JSON document contains the same fields as in the Series: Query method.

/api/v1/series/json/nurswgvml006/df_used?startDate=current_hour&endDate=now&limit=2

Note that the tags object in the JSON response contains all tags in the series key irrespective of which tags are specified in the request.

[
  {
    "entity": "nurswgvml006",
    "metric": "df_used",
    "tags": {
      "disk": "sda1",
      "fstype": "ext4"
    },
    "type": "HISTORY",
    "aggregate": {
      "type": "DETAIL"
    },
    "data": [
      { "t": 1529854360000, "v": 4584832 },
      { "t": 1529854375000, "v": 4584840 }
    ]
  },
  {
    "entity": "nurswgvml006",
    "metric": "df_used",
    "tags": {
      "disk": "sdb1",
      "fstype": "ext4"
    },
    "type": "HISTORY",
    "aggregate": {
      "type": "DETAIL"
    },
    "data": [
      { "t": 1529854360000, "v": 59353568 },
      { "t": 1529854375000, "v": 59407956 }
    ]
  }
]

CSV Format

The response in CSV format contains the header row followed by data rows.

The default header is time,entity,metric,requested tags,value and contains the following columns.

  • time: Value time as Unix time with millisecond precision.
  • date: Value time in ISO format.
  • entity: Entity name.
  • metric: Metric name.
  • tag Columns (if requested).
  • value: Numeric value.

Example for columns=date,t:disk,value.

/api/v1/series/csv/nurswgvml006/df_used?limit=2&startDate=current_hour&endDate=now&t:disk=*&columns=time,t:disk,value

Note that the tag column names in the header do not begin with the t: prefix.

time,disk,value
1529854420000,sda1,4584832
1529854435000,sda1,4584840
1529854420000,sda2,59353568
1529854435000,sda2,59407956

Example

Request

URI

GET /api/v1/series/json/nurswgvml007/mpstat.cpu_busy?startDate=previous_hour&endDate=now

curl

curl "https://atsd_hostname:8443/api/v1/series/csv/nurswgvml007/mpstat.cpu_busy?startDate=previous_hour&endDate=now&limit=3" \
  -k --user {username}:{password}

Response

JSON Format

[
    {
      "entity": "nurswgvml007",
      "metric": "mpstat.cpu_busy",
      "tags": {},
      "type": "HISTORY",
      "aggregate": {
        "type": "DETAIL"
      },
      "data": [
        { "d": "2018-04-27T11:00:09Z", "v": 5.05 },
        { "d": "2018-04-27T11:00:25Z", "v": 3.03 },
        { "d": "2018-04-27T11:00:41Z", "v": 5 }
      ]
    }
]

CSV Format

time,entity,metric,value
2018-05-22T12:00:08Z,nurswgvml007,cpu_busy,26.53
2018-05-22T12:00:24Z,nurswgvml007,cpu_busy,17.35
2018-05-22T12:00:40Z,nurswgvml007,cpu_busy,12.24
2018-05-22T12:00:56Z,nurswgvml007,cpu_busy,15
2018-05-22T12:01:12Z,nurswgvml007,cpu_busy,6.06

Additional Examples

CSV Format Query

← query →