Time-Series API
Use the Time-series API for charting data over time and to generate reports. Time-series use the same underlying data as the Table API, but rows are automatically aggregated and counted over time.
Generic Time-Series Query​
GET /series/{table_code}.{format}?{args}
The time-series API is an abstraction over tables which allows for server-side aggregation of multiple result rows over time. Time-series are meant to be displayed as graphs with time on the x-axis and some aggregate value on the y-axis. Since the underlying data is still in tabular form all table filters work on time-series as well.
Note that this time-series API does not fill gaps. That means when the underlying table contains no data for a particular time interval, the corresponding time-series row will be missing. Clients should be prepared for this case and fill gaps if required.
Intervals between timestamps are equally spaced and can be controlled by the collapse query parameter, i.e. 1d means each interval contains 24 hours of aggregated data. Time-series data can contain fields of all supported numeric data types (e.g. no strings or binary data). The aggregation function is fixed by the semantics of the data type. This may either be a sum, a count, first, last, min, max or mean value.
List of Time-series​
| Endpoint | Time-Series Content |
|---|---|
GET /series/balance | historic end-of-block balances for all accounts |
GET /series/block | aggregated block data |
GET /series/flow | aggregated balances, freezer and delegation flows |
GET /series/op | aggregated operations data |
GET /series/chain | running total counters for on-chain operations, accounts and rolls |
GET /series/supply | running supply totals |
Query Arguments​
Time-series datasets support the following query parameters.
| Argument | Description |
|---|---|
columns optional | Comma separated list of columns you like to fetch. Bulk array results will be ordered accordingly. Default is all defined columns for a series. |
collapse optional | Aggregate numeric data over different sampling intervals. Supported values are 1m (default), 5m, 15m, 30m, 1h, 2h, 3h, 4h, 6h, 12h, 1d, 1w, 1M, 3Mand 1y. |
order optional | Return data in asc (ascending) or desc (descending) order. Default is asc. |
limit optional | Maximum number of aggregated results returned. Limited to 50,000, default 500. |
start_date optional | Start of the time range to query. See timestamps for syntax. |
end_date optional | End of the time range to query. See timestamps for syntax. |
When only start or end date are provided, the other end of the range is deducted from collapse and limit. I.e. with collapse of 1d and limit of 30 you'll get 30 days of data after start_date or before end_date. Called without any optional parameters a query defaults to the most recent 500 minutes (end_date=now, limit=500 and collapse=1m).
Query Filters​
Time-series support the same filters used on tables with the same filter expressions of form <column>.<operator>=<arg>. Filters can be used on all table fields, including fields that are not part of the aggregated result such as addresses and type enums.