--- title: REST API collector slug: rest-api-collector docTags: XBGk0x8JbK4q2KPPqG2qB,GOo15ntkoXThxPf_Z8vVm createdAt: 2025-09-04T10:04:33.073Z --- The REST API collector can read data points from a REST API endpoint. The collector supports reading data points in JSON and CSV format. The collector supports only the OAuth2 authentication. ## Basic settings ### TimestampLayout **Description**: The timestamp layout is used to correctly interpret the timestamp(s) of the data points read for a measurement. A list of available timestamp formats, along with their string representations, can be found [here](https://pkg.go.dev/time#Layout). **Required**: No **If Empty**: The default RFC3339 timestamplayout e.g. `2006-01-02T15:04:05Z07:00` is used. For timestamps in UNIX format, one of the following values can be used: `UNIX` (time in s), `UNIXMILLIS` (time in ms), `UNIXMICROS` (time in μs), or `UNIXNANOS` (time in ns). For other timestamp formats, see the [Read data from JSON](docId\:rkukKRD4aRiWfQk96lqy5) examples. :::hint{type="warning"} Warning: The collector `TimestampLayout` setting is the default `TimestampLayout` setting for all measurements on the collector. It can be overwritten per measurement by setting the `TimestampLayout` setting on the measurement. ::: ### URL **Description**: The URL to the REST API endpoint. **Required**: No. **If Empty**: :::hint{type="warning"} The collector `URL` setting is the default `URL` setting for all measurements on the collector. It can be overwritten per measurement by setting the `URL` setting on the measurement. ::: ### QueryParameters **Description**: A JSON object to configure default query parameters for all requests. This is only used when the `Method` is set to `GET`. The query parameters from the collector or the measurements must contain `` and `` as values of a JSON key. If these are not present, the collector will go into an error status. **Required**: No. **Default:** \{}. The `QueryParameters` from the measurement settings are used. **Example:** ```json { "id": "temperature", "start": "", "stop": "" } ``` The keywords `` and `` are replaced by the collector by the start time and stop time when sending a request. For each request, the start time and stop time are derived from the `Interval` setting. :::hint{type="warning"} Warning: The collector `QueryParameters` setting is the default `QueryParameters` setting for all measurements on the collector. It can be overwritten per measurement by setting the `QueryParameters` setting on the measurement. ::: ### Body **Description**: A JSON object to configure the default Body for all requests. Only in use when the `Method` is set to `POST`. The Body from the collector or the measurements must contain `` and `` as values of a JSON key. If these are not present, the collector will go into an error status. **Required**: No. **If Empty**: The `Body` from the measurement settings are used. **Example:** ```json { "id": "temperature", "start": "", "stop": "" } ``` :::hint{type="warning"} Warning: The collector `Body` setting is the default `Body` setting for all measurements on the collector. It can be overwritten per measurement by setting the `Body` setting on the measurement. ::: ### Method **Description**: The default HTTP(S) request method to be used e.g. `GET` or `POST` **Required**: No. **Default**: the HTTP(S) method `GET` is used. :::hint{type="warning"} The collector `Method` setting is the default `Method` setting for all measurements on the collector. It can be overwritten per measurement by setting the `Method` setting on the measurement. ::: ### Interval **Description**: The interval (in seconds) at which API requests should be sent. Use `-1` to leave empty. **Required**: No. **If Empty**: The `Interval` from the measurement settings is used. **Example: **86400 This sends one request each day. :::hint{type="warning"} The collector `Interval` setting is the default `Interval` setting for all measurements on the collector. It can be overwritten per measurement by setting the `Interval` setting on the measurement. ::: ### IntervalOffset **Description**: The default offset in seconds, relative to the 0th second of each minute, at which requests are sent. Use `-1` to leave empty. **Required**: No. **If Empty**: The `IntervalOffset` from the measurement settings is used. **Example: **1 With one request each day, this sends the request the 1st second after midnight, instead of at midnight itself. :::hint{type="warning"} The collector `IntervalOffset` setting is the default `IntervalOffset` setting for all measurements on the collector. It can be overwritten per measurement by setting the `IntervalOffset` setting on the measurement. ::: ### Headers **Description: **A JSON object to configure default headers for all requests. Use `{}` to leave empty. **Required:** No. **Example**: ```json { "Authorization": "Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "referer": "API-collector" } ``` :::hint{type="warning"} The collector `Headers` setting is the default `Headers` setting for all measurements on the collector. It can be overwritten per measurement by setting the `Headers` setting on the measurement. ::: ### ## Historian re-run settings ### StartTimeHistoric :::hint{type="info"} To start a historic re-run of the data points for all measurements on the collector (in parallel with the realtime run), set the `StartTimeHistoric` setting. ::: **Description**: An optional historic start time. The timestamp Layout must match the `TimestampLayout` setting. **Required**: No. **If Empty: **No historic re-run of the data is started and only live data will be processed. :::hint{type="danger"} Empty the `StartTimeHistoric` when the historic data reading is finished (see the collector logs), to prevent it from being repeated on resuming the collector after a restart or a pause. ::: ### StopTimeHistoric :::hint{type="info"} The `StopTimeHistoric` is only used if the `StartTimeHistoric` is not empty ::: **Description**: An optional historic stop time. The timestamp Layout must match the `TimestampLayout` setting. **Required**: No. **If Empty:** The run for processing historic data will go up to now. ### IntervalHistoric :::hint{type="info"} The `IntervalHistoric` is only used if the `StartTimeHistoric` is not empty. ::: **Description**: An optional interval in seconds that indicates the time difference between the start time and the stop time for each request in a historic re-run (requests are executed each second). **Required**: No. **If Empty: **The interval `900` is set (15 minutes). **Example: **86400 This sends a request for a time period of a day (time between start time and stop time of each request in the historic re-run) at each second (fixed for historic re-run). ## Advanced settings Only collector-specific advanced settings are listed below. ### ReadTimeout **Description**: The HTTP(S) request timeout in seconds. If the collector does not receive a response in this timeframe after the request, the request will be disregarded and an error status is written on the measurements in that request. **Required**: Yes. **Default:** `5` seconds ### IdleTimeout **Description**: Maximum time (in seconds) an idle keep-alive HTTP connection can stay open without any data being sent or received. Once this time passes, the connection will automatically close. **Required**: Yes. **Default:** `0` seconds (means no limit) ### LookBackIntervals **Description**: The amount of intervals (from the `Interval`setting) to additionally look back before each request. **Required**: Yes. **Default:** `0` seconds (means only the current interval will be used as time period for each request) **Example**: If the `Interval` is set to `900` (15 minutes), and the `LookBackIntervals` is set to `3`. Then for each request, the start time will be set 45 minutes before the start time determined by `Interval`, while the stop time of the request is kept. This results in each request setting a time period of 1 hour. :::hint{type="info"} The `LookBackIntervals` is typically used when the REST API server does not hold the data points in realtime, but only holds data points that from some time ago e.g. it does only hold the data points 30 minutes after the fact. ::: ### QueryTimezone **Description**: Specifies the time zone used to interpret query timestamps (for example, the `start` and `stop` time parameters in a request) before formatting them according to the `TimestampLayout` setting. The time zone must be specified using a valid name from the [IANA Time Zone database](https://www.iana.org/time-zones), which you can consult on [wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). **Required**: Yes. **Default:** `UTC` ### AuthType **Description: **Specifies the type of authentication used before making API request. `None` (the default) means no authentication request is made and data requests proceed directly. **Required: **No. **Default: **`None` ### AuthURL **Description: **The endpoint (URL) used to send authentication requests. Only used if **AuthType** is not `None`. **Required: **No. ### AuthInterval **Description: **How often (in seconds) the system should re-authenticate. Only used if **AuthType** is not `None`. **Required: **No. **Default: **`3600` (1 hour) ### AuthID **Description: **The unique identifier (such as a client ID or username) used in authentication requests. Only used if **AuthType** is not `None`. **Required: **No. ### AuthSecret **Description: **The secret key or password used for authentication requests. Only used if **AuthType** is not `None`. **Required: **No. ### AuthUsername **Description: **The username used for authentication requests. Only used if **AuthType** is not `None`. **Required: **No. ### AuthPassword **Description: **The password used for authentication requests. Only used if **AuthType** is not `None`. **Required: **No. ### AuthGrantType **Description: **Specifies the OAuth grant type for authentication requests (e.g., `password`, `client_credentials`). Only used if **AuthType** is not `None`. **Required: **No. **Default: **`password` ### AuthScope **Description:**A comma-separated list of authorization scopes requested during authentication. Only used if **AuthType** is not `None`. **Required: **No. *** ## Measurement settings For the measurement settings that are identical to the collector settings, see the explanation above. For the remanining measurement settings to read data from the REST API responses: - To read data from a JSON payload with the REST API collector, see [Read data from JSON](docId\:rkukKRD4aRiWfQk96lqy5) . - To read data from a CSV payload with the REST API collector, see [Read data from CSV](docId\:QJcpC1w8J8ZNGtA38mPQu) .