Deux points de lecture vous donnent la télémétrie des appareils : latest pour la valeur actuelle de chaque clé, et series pour l’historique. Les deux sont soumis à la permission de lecture de la télémétrie et ne renvoient que les appareils que l’appelant est autorisé à lire. Cette page est la référence, avec des exemples ; voir REST API basics et Authentication pour les clés et les chemins.
Avant de commencer
- Créez une clé API avec la permission de lire la télémétrie (et de lire les appareils, si vous les listez aussi). Le préréglage Read-only suffit. Restreignez les réseaux autorisés de la clé à vos serveurs.
- Trouvez l’identifiant de l’appareil (un UUID) sur la page de l’appareil ou avec
GET /api/iot/devices. - Tous les chemins se trouvent sous votre organisation :
https://<votre hôte>/tenant/<tenantId>/api/.... - Les horodatages sont exprimés en millisecondes depuis le 1er janvier 1970, UTC.
Valeurs actuelles
GET /tenant/{tenantId}/api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity
| Paramètre | Obligatoire | Signification |
|---|---|---|
kind | Oui | iot_device pour la télémétrie des appareils |
entityId | Oui | L’identifiant de l’appareil |
keys | Non | Clés séparées par des virgules, 50 au maximum. Omettez pour toutes les clés. |
{
"kind": "iot_device",
"entityId": "6f1c…",
"latest": {
"temperature": { "ts": 1759572000000, "value": 21.5 },
"humidity": { "ts": 1759572000000, "value": 40 }
}
}
Une clé que l’appareil n’a jamais envoyée est absente de latest.
Séries
GET /tenant/{tenantId}/api/telemetry/series?kind=iot_device&entityId={deviceId}&keys=temperature&from=1759568400000&to=1759572000000&bucket=auto&agg=avg
| Paramètre | Obligatoire | Valeurs | Par défaut |
|---|---|---|---|
kind | Oui | iot_device | |
entityId | Oui | L’identifiant de l’appareil | |
keys | Oui | Séparées par des virgules, de 1 à 50 clés, chacune respectant les règles de clés | |
from | Oui | Début, inclus (epoch en ms) | |
to | Oui | Fin, exclue (epoch en ms) ; doit être postérieure à from | |
bucket | Non | auto, raw, 1m, 1h, 1d | auto |
agg | Non | avg, min, max, last, sum, count, increase | avg |
limit | Non | Points par clé, de 1 à 10 000 | 10,000 |
{
"kind": "iot_device",
"entityId": "6f1c…",
"resolution": "1m",
"agg": "avg",
"series": {
"temperature": [
{ "ts": 1759568400000, "value": 21.2 },
{ "ts": 1759568460000, "value": 21.4 }
]
}
}
resolutionest la résolution réellement utilisée. Avecbucket=auto, elle vautrawpour les fenêtres allant jusqu’à 24 heures, puis1m,1hou1d, selon la plus fine qui donne moins de 10 000 intervalles.- Avec un intervalle,
tsest le début de l’intervalle (aligné sur UTC) etvaluel’agrégat. Les intervalles sans mesure sont absents, et non à zéro. - Avec
raw, chaque valeur stockée est renvoyée telle qu’elle a été stockée (nombres, texte, booléens, JSON), un point par horodatage, du plus ancien au plus récent ;aggest ignoré. - Les points sont triés par temps. Une clé sans données renvoie une liste vide.
Voir Aggregates and rollups pour ce que renvoie chaque agg.
Limites
| Limite | Valeur |
|---|---|
| Clés par requête | 50 |
| Points par clé | 10 000 (limit) |
| Intervalles dans une fenêtre | 10 000 à la résolution choisie, sinon 400 range_too_large |
| Valeurs brutes | Uniquement dans votre conservation brute (90 jours au maximum) |
| Intervalles à la minute | Seulement dans la rétention des minutes (31 jours au maximum) |
| Requêtes | La limite de débit de l’API ; 429 avec Retry-After en cas de dépassement. Voir Errors and rate limits. |
Erreurs
| Statut | Corps | Cause |
|---|---|---|
| 400 | { "message": "to must be after from" } | to n’est pas postérieur à from |
| 400 | { "message": "bad keys" } | keys vide, plus de 50 clés, ou une clé qui ne respecte pas les règles de clés |
| 400 | { "message": "…", "code": "range_too_large" } | Trop d’intervalles pour la fenêtre ; utilisez un bucket plus grossier |
| 401 / 403 | Aucune clé valide, ou la clé n’a pas la permission | |
| 404 | { "message": "Not found" } | L’appareil n’existe pas, ou vous n’avez pas le droit de le lire (même réponse dans les deux cas) |
| 429 | Limite de débit |
Pagination des valeurs brutes
Une lecture brute renvoie au maximum 10 000 points par clé, du plus ancien au plus récent. Pour en lire davantage :
- Demandez
bucket=raw&limit=10000pour votre fenêtre. - Si une clé a renvoyé 10 000 points, redemandez avec
fromégal autsdu dernier point + 1. - Répétez jusqu’à ce qu’une clé renvoie moins de
limitpoints.
Pour de longues périodes, privilégiez les intervalles 1m ou 1h : ils contiennent le min, le max, la somme, le nombre et la dernière valeur de chaque intervalle, en une valeur chacun.
Exemples
Valeurs actuelles avec curl :
curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
"https://$HOST/tenant/$TENANT/api/telemetry/latest?kind=iot_device&entityId=$DEVICE&keys=level,pump_running"
Maximum horaire d’une pression sur les 7 derniers jours :
TO=$(date +%s000); FROM=$((TO - 7*24*3600*1000))
curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
"https://$HOST/tenant/$TENANT/api/telemetry/series?kind=iot_device&entityId=$DEVICE&keys=pressure&from=$FROM&to=$TO&bucket=1h&agg=max"
Énergie consommée par heure (un compteur kWh qui ne fait que croître) sur une journée :
curl -s -H "Authorization: Bearer $HERMETRY_KEY" \
"https://$HOST/tenant/$TENANT/api/telemetry/series?kind=iot_device&entityId=$DEVICE&keys=energy_kwh&from=1762642800000&to=1762729200000&bucket=1h&agg=increase"
Totaux journaliers dans votre fuseau horaire
Les intervalles journaliers sont des jours UTC. Pour un jour local, lisez les increase (ou sum) horaires et additionnez les heures qui appartiennent à chaque jour local :
// Node.js 18+: daily energy per local day (Europe/Istanbul) for the last 7 days
const tz = 'Europe/Istanbul';
const to = Date.now();
const from = to - 7 * 24 * 3600 * 1000;
const url = `https://${host}/tenant/${tenant}/api/telemetry/series?kind=iot_device&entityId=${device}`
+ `&keys=energy_kwh&from=${from}&to=${to}&bucket=1h&agg=increase`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
const { series } = await res.json();
const days = {};
for (const p of series.energy_kwh) {
const day = new Date(p.ts).toLocaleDateString('en-CA', { timeZone: tz }); // YYYY-MM-DD
days[day] = (days[day] ?? 0) + p.value;
}
console.log(days);
La première heure de la fenêtre ne compte que ce qui a augmenté à l’intérieur de celle-ci ; commencez donc la fenêtre une heure avant le premier jour local voulu, et écartez cette heure. Un fuseau avec un décalage d’une demi-heure nécessite des intervalles 1m, qui remontent au plus à 31 jours.
Autres routes de lecture
| Route | Fonction |
|---|---|
GET /api/telemetry/kinds | Les types de mesures de votre organisation (par exemple iot_device) |
GET /api/iot/devices/{deviceId}/elements | Les clés d’un appareil (déclarées dans son profil ou envoyées), 300 au maximum, avec libellés et unités |
Pour les écritures, les appareils utilisent MQTT ou HTTP ; l’API REST n’a pas de route d’écriture de télémétrie. Voir Device HTTP API et Telemetry and attributes API.

