Documentation Index
Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
Use this file to discover all available pages before exploring further.
Examples use externalId for asset-centric projects. For data modeling, use instanceId instead. See Time series and datapoints for details. Europe/Oslo or America/New_York. We also support time zones with half-hour offsets, like Asia/Kolkata (UTC+05:30) or 15 minute offsets, like Asia/Kathmandu (UTC+05:45). You can also enter a custom time zone, like UTC+02:30. If nothing is specified, we default to UTC.
Queries over time zones with non-zero minute offsets may be slower than time
zone queries with whole hour offsets. If queries start to fail, try to use a
smaller time range or use a lower limit.
Aggregate granularities
Calendars can be used with three granularities, hour, day, and month. The minutesand second aggregates do not change with the chosen calendar.
Month
Month is denoted by month or mo (not to be confused with m for minute). The month starts on the first day in the month, at 00:00 in the given time zone, and ends (exclusively) on the first day of the next month.
Month aggregates take DST transitions into account, which means that, for instance, the length of March and October may vary, depending on the time zone.
Just like other aggregates, you can prefix the granularity with a number, like 3month or 12mo. This way, you can retrieve aggregates for a quarter or a year. The offset is determined by the start time. For example, if you query for 3month starting at 2022-02-01 (in the given time zone), you will get the aggregates for February through April, May through July, August through October, and November through January.
Day
Day is denoted by day or d, starts at 00:00 in the given time zone, and ends (exclusively) at 00:00 the next day.
Day aggregates will take DST transitions into account, in which case the length of the day can be more or less than 24 hours.
Hour
Hour aggregates (denoted by hour or h) will in general behave the same as when the time zone is not set. The only relevant change is when the time zone has an offset that is not a whole hour, like Asia/Kolkata. In this case, we will round the start time down to the nearest whole hour in the given time zone.
Hour aggregates do not take regular DST transitions into account. 24h is, in general, always 24 hours, even if the day is 23 or 25 hours long.
Synthetic time series
In synthetic time series, time zones and calendar queries are analogous to regular aggregate queries.
We support the exact same granularities and time zones.
The time zone is provided for the query as a whole, while the granularities are specified for each time series in the query. The alignment of each time series is rounded down to the nearest whole granularity unit in the given time zone. For instance, 7d will align to local midnight of the day of the alignment timestamp.
The default alignment is epoch, or January 1st 1970 UTC. If you use a time zone with a negative offset, like America/Chicago (UTC-05:00), epoch corresponds to December 31st 1969 local time, which for month aggregates will round down to December 1st 1969.If this is not the intended behavior, please specify the correct alignment in the expression.
Special cases
We only support queries with offsets that are multiple of 15 minutes, not like
UTC+05:21:10 (Asia/Kolkata until 1905). Such unaligned offsets were more
common at the start of the 20th century, and were abolished after 1980. Use a
later start time, or use a different time zone, for instance fixed
UTC+05:30.
24h is not 24 hours, during transitions that are not a whole
hour.
If there are two midnights on a given day (DST transition from 01:00 to 00:00), we will use the
first midnight as the dividing point.
Example queries
Retrieve data points
POST /api/v1/projects/{project}/timeseries/data/list
Content-Type: application/json
{
"items": [
{
"limit": 100,
"externalId": "your external id",
"aggregates": ["count"],
"granularity": "3mo",
"timeZone": "Australia/Adelaide",
"start": 1580500000000
}
]
}
Response:
{
"items": [
{
"id": 123,
"externalId": "your external id",
"isString": false,
"isStep": false,
"datapoints": [
{
"timestamp": 1580477400000,
"count": 2
},
{
"timestamp": 1588257000000,
"count": 1
},
{
"timestamp": 1604151000000,
"count": 5
}
]
}
]
}
POST /api/v1/projects/{project}/timeseries/data/list
Content-Type: application/json
{
"items": [
{
"externalId": "your external id",
"granularity": "1day"
},
{
"externalId": "your external id",
"granularity": "6h"
}
],
"start": 1582144200000,
"aggregates": ["count"],
"timeZone": "UTC+01:00",
"limit": 1
}
Response:
{
"items": [
{
"id": 123,
"externalId": "your external id",
"isString": false,
"isStep": false,
"datapoints": [
{
"timestamp": 1582066800000,
"count": 2
}
]
},
{
"id": 123,
"externalId": "your external id",
"isString": false,
"isStep": false,
"datapoints": [
{
"timestamp": 1582142400000,
"count": 5
}
]
}
]
}
start, aggregates, and timeZone for all queries.
The start time, 1582144200000, corresponds to Feb 19 2020 21:30:00 UTC+01:00. For the day aggregate, we round down to the start of the day, for the 6h aggregate, we round down to the nearest hour, or 21:00 UTC+01:00.
Note that the count may be higher for the 6h aggregate, as it may include data points from the next day.
Retrieve synthetic data points
POST /api/v1/projects/{project}/timeseries/synthetic/query
Content-Type: application/json
{
"items": [
{
"expression": "TS{id:123, aggregate:'stepinterpolation', granularity:'3mo', alignment:0} + TS{id:234}",
"timeZone": "Europe/Oslo"
}
]
}
Response:
{
"items": [
{
"datapoints": [
{
"timestamp":7772400000,
"value":15.0
}
,
{
"timestamp":13478400000,
"value":16.0
}
,
{
"timestamp":15634800000,
"value":21.0
}
,
{
"timestamp":20003696000,
"value":22.0
}
],
"isString":false
}
]
}
