Skip to content
Eigen Documentation

Retreiving Data

Historian Multi Request API is set of Ingenuity APIs for retrieving any arbitrary set of data stored in connected historians, timeseries databases.

1. Authentication

Section titled “1. Authentication”

All requests need to be authenticated using API Key, passed as apikey query parameter or X-Api-Key HTTP header.

2. Limits

Section titled “2. Limits”

Set of requests will return error if not all sub-requests were retrieved within 30s. This is to prevent server overload and to return response before proxy timeouts are hit.

For a single request, following checks are evaluated before execution:

2.1. Maximum number of points requested

Section titled “2.1. Maximum number of points requested”

  • Default:100,000

  • Description: This is the total number of points requested across all requests in a single call.

    • For RAW_POINTS, this corresponds to maxPoints
    • For INTERPOLATED_POINTS, this corresponds to count
    • All other request types count as 1 point each

2.2. Maximum number of effective points

Section titled “2.2. Maximum number of effective points”

  • Default:500,000

  • Description: This represents the actual load on the historian, accounting for how many underlying points must be fetched.

    Example:

    calc/ADD(tagA,tagB) counts as points(tagA) + points(tagB)

    This value can increase rapidly when using:

    • calculated tags (calc/...)
    • wide time ranges
    • interpolated queries

    2.3. Maximum number of effective tags

    Section titled “2.3. Maximum number of effective tags”
    • Default:100
    • Description: This counts the number of underlying tagsrequired to fulfil a request.

    Example: calc/ADD(tagA, calc/SUB(tagB, tagC)) counts as:

    • tagA
    • tagB
    • tagC

    → Total: 3 effective tags

3. Request structure

Section titled “3. Request structure”

All requests must be ran as POST request and provided a json payload as below. Each request follows similar pattern:

{
  "now": "2024-02-01T12:00:00Z", // optional `now` parameter, defaults to wall clock now
  "timeZone": "Europe/Oslo", // optional time zone parameter, defaults to Ingenuity time zone
  "requests": {
    "request1": {
      // label of first request, response will be returned under the same key
      "type": "REQUEST_TYPE",
      "tag": "historianName/tagName",
      "details": {} // additional parameters for given request
    }
    // more requests can be added here with unique labels
  }
}

3.1 Timestamp Formats

Section titled “3.1 Timestamp Formats”

Some methods require a timestamp field, our APIs accept several formats:

  • Most ISO Formats
    • 2026-04-22T23:59:49Z
    • 2026-04-22T21:59:49+02:00
    • 2026-04-22T21:59:49[Europe/Oslo]
  • Unix/Epoch Seconds or Milliseconds
    • 1776902389
    • 1776902389000
  • Relative Timestamps
    • now
    • yesterday
    • 4 hours ago
    • 7 days ago at 00:00
    • today at midnight

4. Request Types/Methods

Section titled “4. Request Types/Methods”

All queries require a historian name and a tag name

Request Type

CURRENT_POINT

Input Parameters

  • now: timestamp (Optional)

Description

Return current value of given tag. If now parameter is passed in request, these requests are returning last known point before this timestamp

Example

Request:

{
  "requests": {
    "label": {
      "type": "CURRENT_POINT",
      "tag": "calc/TOTALISE2(constants/1, MONTH, BEGIN_MONTH, 1d)",
      "details": {}
    }
  }
}

Result:

{
  "results": {
    "label": {
      "dataPoint": {
        "timestamp": "2023-09-25T17:29:04.446620788+02:00",
        "value": 24.728523680555632
      }
    }
  },
  "errors": {},
  "now": "2023-09-25T17:29:04.446620788+02:00"
}

Curl Sample

Terminal window
curl -X POST \
https://demo.eigen.co/historian/multi \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: READONLYKEY' \
  --insecure \
  -d '
  {
    "requests": {
      "label": {
        "type": "CURRENT_POINT",
        "tag": "calc/TOTALISE2(constants/1, MONTH, BEGIN_MONTH, 1d)",
        "details": {}
      }
    }
  }
'