This guide explain how to retrieve historical and latest prediction results from the API for use in your own dashboards or integrations.
Table of Contents
Overview
Predictions are stored as time-series data indexed by the time they are predicting for (datetime_measure). You can query them specifically by Target ID (recommended) or by broader categories like Metric and Location.
1. Query by Specific Target
If you know the Target ID (Virtual Sensor ID) for a specific job, you can query its predictions directly. This is the fastest and most accurate way to fetch a single time-series.
GET /api/v1/targets/{id}/predictions
Example Request:
curl "http://localhost:8080/api/v1/targets/<TARGET_UUID>/predictions?gte=2024-04-16T00:00:00Z" \
-H "Authorization: Bearer <your_token>"- Query Params:
gte,lte,limit,order.
2. Query by Metric & Location
This is useful for fetching data across multiple targets or when the specific Target ID is unknown.
GET /api/v1/predictions
Required Parameters:
metric(string): The metric to retrieve (e.g.,temperature).location_id(UUID): The ID of the location.from/to(optional): Time range filters.
Response Shape & Types
All prediction retrieval endpoints return a JSON array of prediction objects:
[
{
"datetime_measure": "2024-04-16T12:00:00Z",
"value_num": 18.5,
"confidence": 0.95,
"target_id": "target-uuid-...",
"meta": { "model_version": "1.0.3" }
}
]Internal Logic: The datetime_measure refers to the time the prediction is for (the forecasted time), not the time it was calculated. If you need the calculation time, look for the run_at field in the full API response.