Querying Chart Data

Return Chart Data

The charts endpoint allows you to query for chart data out of HyperDX.

Request

POST /api/v1/chart/series

Request Body Parameters

startTime - (Number) Start time in milliseconds since epoch

endTime - (Number) End time in milliseconds since epoch

granularity - (String, Optional) Granularity of each time window. Omitting this will return all data aggregated across the entire time range. Valid values: 30 second, 1 minute, 5 minute, 10 minute, 15 minute, 30 minute, 1 hour, 2 hour, 6 hour, 12 hour, 1 day, 2 day, 7 day, 30 day.

seriesReturnType - (String, Optional) Whether to return each series as a column, or to treat the first two series as a ratio.

Series

series - (Series[]) An array of series to query for (max 5). Each series is an object with the following properties:

series.dataSource - (String) Whether to query for metrics or for events (logs and spans).

series.aggFn - (String) How to aggregate the data. Valid values: avg, count, count_distinct, max, min, p50, p90, p95, p99, sum. Sum-type metrics (opens in a new tab) also support (avg|max|min|p50|p90|p95|p99|sum)_rate aggregations as well to treat the metric as a rate.

series.field - (String, Optional) The event field or metric name to query for, not required for count aggregations. (ex. level)

series.where - (String) A search query to filter the data by, leave as empty if a filter is not required. (ex. level:err)

series.groupBy - (String[]) An array of fields to group by (ex. [level, service]). All series must have the same exact value.

series.metricDataType - (String, Optional) Required for metric data, whether to query for Sum, Gauge, or Histogram type.

Request Example

curl --request POST \
  --url https://api.hyperdx.io/api/v1/charts/series \
  --header 'Authorization: Bearer YOUR_PERSONAL_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "series": [
    {
      "dataSource": "events",
      "aggFn": "sum",
      "field": "hyperdx_event_size",
      "where": "level:err",
      "groupBy": ["service"]
    },
    {
      "dataSource": "events",
      "aggFn": "count",
      "field": "",
      "where": "",
      "groupBy": ["service"]
    }
  ],
  "endTime": 1706135088919,
  "startTime": 1706131488903,
  "granularity": "1 minute",
  "seriesReturnType": "column"
}'

Response

Response Parameters

data - (Object[]) An array of objects, each object represents a time window.

data.ts_bucket - (Number) The start time of the time window in milliseconds since epoch.

data.series_N.data - (Number) The value of the series at the given time window. The series numbering are returned in the same order as they were requested.

data.group - (String[]) The group by values for the given time window.

Response Example

{
  "data": [
    {
      "series_0.data": 852,
      "series_1.data": 2,
      "group": ["hdx-oss-dev-api"],
      "ts_bucket": 1706131440000
    },
    {
      "series_0.data": 364980,
      "series_1.data": 254,
      "group": ["hdx-oss-dev-task"],
      "ts_bucket": 1706131500000
    }
  ]
}