This section details the endpoints used to read data from Io-base metrics.
Retrieve aggregated values for a metric
Description
This request allows you to retrieve a series of aggregated values (e.g., average, sum) for a metric over regular time intervals.
GET /v2/data/aggregated-values
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
MetricName (required): Name of the metric to query.
Datasource (required): Datasource of the metric (e.g., prod).
Start (required): Start date of the period (ISO 8601 format).
End (required): End date of the period (ISO 8601 format).
Function (required): Aggregation function to use (Avg, Sum, Min, Max, Count, Median, StdDev, First, Last, Integral).
Interval (required): Interval for grouping aggregations (10m, 1h, 1d...).
Timezone (optional): Time zone for interval alignment (IANA format, e.g., Europe/Paris).
Limit (optional): Limits the number of returned points (max 50000).
Annotations (optional): If true, includes annotations in the response.
These parameters must be added to the end of the URL to build the query string. The first is preceded by a "?" and the following ones are separated by an "&":
.../aggregated-values?MetricName=[metric_name]&Datasource=[datasource]&Start=[start_date]&End=[end_date]&Function=[agg_function]&Interval=[time_interval]&Limit=[limit]
Example request:
# Request to calculate the average per 30-minute interval.
curl -X GET \
"https://xxx.indaba.api.indasuite.io-base.com/v2/data/aggregated-values?MetricName=documentation&Datasource=main&Start=2025-06-26T08:00:00Z&End=2025-06-26T10:00:00Z&Function=Avg&Interval=30m" \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
Valid reponse (200 OK) :
{
"values": [
{
"timestamp": "2025-06-26T10:00:00+02:00",
"value": 115.5
},
{
"timestamp": "2025-06-26T10:30:00+02:00",
"value": 118.2
}
],
"isResponseComplete": true,
"name": "metric4test_ok",
"datasource": "main"
}
Pagination Handling (isResponseComplete)
Please refer to the section on pagination handling.
Common Errors
Please refer to the list of common errors.
Retrieve a single aggregated value
Description
This request allows you to retrieve a single aggregated value (e.g., average, sum) for a metric over an entire period.
GET /v2/data/aggregated-value
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
MetricName (required): Name of the metric to query.
Datasource (optional): Datasource of the metric.
Start (required): Start date of the period (ISO 8601 format).
End (required): End date of the period (ISO 8601 format).
Function (required): Aggregation function to use (Avg, Sum, Min, Max, Count, Median, StdDev, First, Last, Integral).
Interval (optional): Time interval for the calculation (e.g., 1h).
Timezone (optional): Time zone for interval alignment (IANA format).
These parameters must be added to the end of the URL to build the query string. The first is preceded by a "?" and the following ones are separated by an "&":
.../aggregated-value?MetricName=[metric_name]&Start=[start_date]&End=[end_date]&Function=[agg_function]
Example request
# Command to retrieve the average of a metric over one hourcurl -X GET \ 'https://xxx.indaba.api.indasuite.io-base.com/v2/data/aggregated-value?MetricName=metric4test_ok&Datasource=main&Start=2025-06-26T07:06:00Z&End=2025-06-26T08:06:00Z&Function=Avg' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
Valid reponse (200 OK) :
{
"timestamp": "2025-06-26T07:06:00+00:00",
"value": 123,
"name": "metric4test_ok",
"datasource": "main"
}
Common Errors
Please refer to the list of common errors.
Retrieve raw (unaggregated) values
Description
This request retrieves the raw (unaggregated) values for a metric over a time range.
GET /v2/data/values
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
MetricName (string, required): Name of the metric.
Datasource (string, optional): Datasource of the metric.
Start (date-time, required): Start date of the period (ISO 8601 format).
End (date-time, required): End date of the period (ISO 8601 format).
Limit (integer, optional): Limits the number of returned points (max 50,000).
Timezone (string, optional): Time zone for date interpretation.
OrderBy (string, optional): Sorts the results by timestamp. Possible values:
ASC(ascending) orDESC(descending).Filter (string, optional): Filtering expression on values (e.g.,
value > 100).Annotations (boolean, optional): If
true, includes annotations in the response.
These parameters must be added to the end of the URL to build the query string. The first is preceded by a "?" and the following ones are separated by an "&":
General syntax of the GET request :
.../values?MetricName=[metric_name]&Datasource=[source]&Start=[start_date]&End=[end_date]&Limit=[limit]&OrderBy=[ASC|DESC]&Filter=[filter_expression]&Annotations=[true|false]&Timezone=[timezone]
Example request
# Command to retrieve the last 100 raw values greater than 50, sorted in descending order.
curl -X GET \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data/values?MetricName=metric4test_ok&Datasource=main&Start=2025-06-26T07:06:00Z&End=2025-06-26T08:06:00Z&Limit=100&OrderBy=DESC&Filter=value>50' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
Valid reponse (200 OK) :
{
"values": [
{
"timestamp": "2025-07-01T13:50:55.8349135+00:00",
"value": 45
},
{
"timestamp": "2025-07-01T14:50:55.8349142+00:00",
"value": 100.21
}
],
"isResponseComplete": true,
"name": "cip_30",
"datasource": "test",
"unit": "°C"
}
Pagination Handling (isResponseComplete)
Please refer to the section on pagination handling.
Common Errors
Please refer to the list of common errors.
Retrieve the last value for one or more metrics
Description
This request retrieves the last recorded value for one or more metrics. All parameters are provided in the request body.
POST /v2/data/query/values/latest
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
metrics (array of objects, required): A list of the metrics to query.
metricName (string, required): The name of the metric.
datasource (string, optional): The datasource.
targetUnit (string, optional): The unit in which the value should be returned.
timezone (string, optional): The timezone for date interpretation.
The following parameters must be provided in the request body, in JSON format.
General syntax of the request body :
{ "metrics": [ { "metricName": "metric_name_1", "datasource": "datasource" }, { "metricName": "metric_name_2" } ], "timezone": "time_zone" }
Example request
# Command to retrieve the last value for three metrics
curl -X POST \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/data/query/values/latest' \
# ----- Headers -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Body -----
-d '
{
"metrics": [
{ "metricName": "metric4test_ok", "datasource": "main" },
{ "metricName": "metric_accessible_2", "datasource": "main" },
{ "metricName": "metric_inaccessible", "datasource": "main" }
]
}
'
Responses
Example of a valid response (200 OK) :
This request can query multiple metrics simultaneously. Therefore, its response is structured to handle success and failure on a per-metric basis.
For this reason, the request always returns a global 200 OK status, and it is within the response body that each metric is assigned a "status" field to indicate whether the operation was successful.
If access is denied, no value is assigned to the metric in the response.
Below is an example of a response for a request on three metrics:
The first is returned successfully (status 200).
The second is inaccessible to the user as they do not have the necessary rights (status 403).
The third does not exist in the repository (status 404).
[
{
"status": 200,
"timestamp": "2025-07-02T09:22:41Z",
"value": 123.5,
"name": "metric_accessible_1",
"datasource": "main"
},
{
"status": 403,
"name": "metric_inaccessible",
"datasource": "main"
},
{
"status": 404,
"timestamp": "2025-07-02T09:20:15Z",
"value": 99.9,
"name": "metric_accessible_2",
"datasource": "main"
}
]
For more information on error statuses, please refer to the list of common errors.
Retrieve the last value for a single metric
Description
This request retrieves the last known value for a single metric. It is an optimized version of the corresponding POST request, simpler and more efficient for the use case of a single metric.
GET /v2/data/values/latest
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
MetricName (required): Name of the metric.
Datasource (optional): Datasource.
These parameters must be added to the end of the URL to build the query string. The first is preceded by a "?" and the following ones are separated by an "&":
.../values/latest?MetricName=[metric_name]&Datasource=[datasource]
Example request
# Command to retrieve the last value for a metric.
curl -X GET \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data/values/latest?MetricName=metric4test_ok&Datasource=main' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
Example of a valid response (200 OK) :
{
"timestamp": "2025-06-26T10:04:52+02:00",
"value": 123,
"name": "metric4test_ok",
"datasource": "main"
}
Common Errors
Please refer to the list of common errors.
Retrieve a value at a specific time for multiple metrics
Description
This request retrieves the value of multiple metrics at a specific point in time (or the value immediately before/after that moment).
POST /v2/data/query/values/instant
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
The following parameters must be specified in the request body :
moment (date-time, required): The specific point in time to query.
metrics (array of objects, required): A list of the metrics to query.
metricName (string, required): The name of the metric.
datasource (string, optional): The datasource.
targetUnit (string, optional): The unit in which the value should be returned.
rangeLimiter (string, required): Limits the search in time (e.g., 30m).
queryDirection (string, optional):
Before_moment(default) orAfter_moment.timezone (string, optional): The timezone for date interpretation.
Example request
# Command to retrieve the value of three metrics before 1:00 PM
# limiting the search to a 30-minute window.
curl -X POST \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/data/query/values/instant' \
# ----- Headers -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Body -----
-d '
{
"moment": "2025-06-27T13:00:00+02:00",
"rangeLimiter": "30m",
"metrics": [
{ "metricName": "metric4test_ok", "datasource": "main" },
{ "metricName": "metric_accessible_2", "datasource": "main" },
{ "metricName": "metric_accessible_3", "datasource": "main" }
]
}
'
Responses
Example of a valid response (200 OK) :
This request can query multiple metrics simultaneously. Therefore, its response is structured to handle success and failure on a per-metric basis.
For this reason, the request always returns a global 200 OK status, and it is within the response body that each metric is assigned a "status" field to indicate whether the operation was successful.
If access is denied, no value is assigned to the metric in the response.
Below is an example of a response for a request on three metrics:
The first is returned successfully (status 200).
The second is inaccessible to the user as they do not have the necessary rights (status 403).
The third does not exist in the repository (status 404).
[
{
"status": 200,
"timestamp": "2025-07-02T09:22:41Z",
"value": 123.5,
"name": "metric_accessible_1",
"datasource": "main"
},
{
"status": 403,
"name": "metric_inaccessible",
"datasource": "main"
},
{
"status": 404,
"timestamp": "2025-07-02T09:20:15Z",
"value": 99.9,
"name": "metric_accessible_2",
"datasource": "main"
}
]
For more information on error statuses, please refer to the list of common errors.
Retrieve a value at a specific time (single metric)
Description
This request retrieves the value of a single metric at a specific point in time (or the value immediately before/after that moment).
GET /v2/data/values/instant
Scope
To execute this request, you must have the following scope: metrics:read.
Parameters
MetricName (string, required): Name of the metric.
Datasource (string, optional): Datasource of the metric.
Moment (date-time, required): The specific point in time to query (ISO 8601 format).
RangeLimiter (string, required): Restricts the search to a time interval (e.g., 30m).
QueryDirection (string, optional): Specifies whether to search for the value before (
Before_moment, default) or after (After_moment) the given time.
These parameters must be added to the end of the URL to build the query string. The first is preceded by a "?" and the following ones are separated by an "&".
Example request
curl -X GET \
"https://xxx.indaba.api.indasuite.io-base.com/v2/data/values/instant?MetricName=metric_test&Datasource=test&Moment=2020-01-26T13:00:00%2B01:00&QueryDirection=after_moment&RangeLimiter=30m" \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Responses
Valid reponse (200 OK) :
{
"timestamp": "2025-01-26T13:29:08.000+01:00",
"value": 0.422,
"name": "meas_doc1",
"datasource": "test"
}
Common Errors
Please refer to the list of common errors.
Pagination management
For performance reasons, when you request data over a long period, the API may return the results in several parts. Some responses include a boolean field named isResponseComplete to handle this.
If
isResponseCompleteis true: You have received all the data for the requested period.If
isResponseCompleteis false: There is more data to retrieve. To get the next part, you must make a new request with adjusted parameters:Get the timestamp of the last data point received.
Make an identical request, but use this timestamp as the new start date (
Start).Repeat this process until the response contains
isResponseComplete: true.
Common errors
You will primarily encounter the following HTTP error codes:
400 Bad Request: Your request is malformed. This may be due to a missing parameter, an incorrect data type, or invalid JSON. The response body will contain an
errorsarray detailing the problem.
{
"errors": [
{
"error": "Field Required",
"message": "The xxx field is required."
}
],
"statusCode": 1050,
"message": "Invalid request"
}
403 Forbidden: Your authentication token is valid, but you do not have the necessary rights for this action. This can happen for two reasons:
Your token does not have the required scope (e.g., you are trying to write data without the metrics:write scope).
Your token has the correct scope, but your user (or service account) is not linked to an authorization that grants access to the requested metric.
404 Not Found: The resource you are trying to reach does not exist. This typically occurs if you are using an incorrect ID or requesting a metric that does not exist.