Retrieve historical time-series data for a single metric

POST 
https://ServerIP:PortNumber/api/v1/query/metric/histogram

This endpoint retrieves time-series data for a single specified metric over a given timeline. The data is displayed as a series of data points, each representing a specific moment in time. Users can specify a metric (e.g., system.cpu.percent), the entity type (e.g., monitor), and a list of specific entities. The data can be aggregated using methods such as avg (average) or others based on the user's request. Additionally, the timeline and granularity can be customized, allowing for detailed insights into both current and historical performance metrics.

Request

application/json

Body

required

queries object[]required
A list of queries to retrieve time-series data for a single metric.
Array [
aggregator stringrequired
The method of aggregation for the data points, such as 'avg', 'sum', 'min', 'max', and 'count'
data.point stringrequired
The specific metric to query, such as 'system.cpu.percent'. Only one metric can be queried in this endpoint.
entity.type string
The type of entity for which data is being retrieved, for example, 'monitor'.
entities integer[]
The specific entity IDs to query the data for. The ID could be a Monitor ID, Group ID, or a Tag value based on the 'entity.type' you have selected
]
data.filter object

Used to filter the data based on specific conditions. Multiple groups of filters can be combined using logical operators.

groups object[]

Defines groups of conditions for the pre-filter. Each group consists of multiple conditions that can be combined with a logical operator. You can add a maximum of 3 groups at once.

Array [

conditions object[]

List of individual conditions within the group. Each condition specifies a field, an operator, and a value. You can add a maximum of 3 conditions at once.

Array [

operand string

The field to apply the condition on, such as a metric.

operator string

The comparison operator used for filtering. For string values, the possible values are 'in', 'start with', 'end with', '=', and 'contain'. For integer values, the possible values are '=', '>', '>=', '<', '<='

value string

The value to compare the operand against.

]

filter string

Defines whether this group is an inclusion or exclusion filter. The possible values are 'include' and 'exclude'.

operator string

Logical operator to combine conditions within the group. The possible values are 'and' and 'or'.

]

filter string

Defines whether the overall pre-filter is an inclusion or exclusion filter. The possible values are 'include' and 'exclude'.

operator string

Logical operator to combine all groups in the pre-filter. The possible values are 'and' and 'or'.

result.filter object

Specifies the post-filters applied to the time-series results. This attribute allows users to refine the output by including or excluding results based on defined conditions.

conditions object[]

List of conditions to filter the time-series results. Each condition specifies a field, an operator, and a value. You can add a maximum of 3 conditions at once.

Array [

operand string

The field to apply the condition on, such as a metric.

operator string

The comparison operator used for filtering. For string values, the possible values are 'in', 'start with', 'end with', '=', and 'contain'. For integer values, the possible values are '=', '>', '>=', '<', '<='

value integer

The value to compare the operand against.

]

filter string

Defines whether the post-filter is an inclusion or exclusion filter. The possible values are 'include' and 'exclude'.

operator string

Logical operator to combine all conditions in the post-filter. The possible values are 'and' and 'or'.

timeline objectrequired

Defines the time range for the data being retrieved. This includes the start and end dates and times.

from.date daterequired

The start date for the data retrieval.

from.time timerequired

The start time for the data retrieval.

to.date daterequired

The end date for the data retrieval.

to.time timerequired

The end time for the data retrieval.

granularity stringrequired

Defines the granularity (sampling interval) for the data. The granularity field must follow the standard time format, where time intervals are represented as '1 s' for 1 second, '1 m' for 1 minute, '1 h' for 1 hour, '1 d' for 1 day.

type stringrequired

Specifies the type of data to be retrieved, such as 'metric'. The possible type of data that can be retrieved are 'metric' and 'availability'.

result.by string[]

An array of strings specifying how the results should be grouped, The possible values are 'monitor', 'tag', 'group', and 'instance'.

Responses

200

Successfully retrieved Historical data with respect to data point with specific aggregator and specific entity type.

application/json

Schema

Schema

oneOf
Performance_Instance_Metric_Histogram_Category
response-code integer
status string
result object[]
Array [
monitor string
object.ip string
id number
object.id integer
metric string
aggregator string
value integer
Timestamp number
]
Performance_Scalar_Metric_Histogram_Category
response-code integer
status string
result object[]
Array [
monitor string
instance.name string
metric string
aggregator string
value integer
object.ip string
id number
object.id integer
Timestamp integer
]

Example (from schema)

{}

400

The request was invalid. Possible reasons could include missing required parameters or incorrect parameter values.

application/json

Schema

Schema

response-code integer
status string
message string
error.code string

Example (from schema)

{
  "response-code": 400,
  "status": "fail",
  "message": "Bad request",
  "error.code": "MD031"
}

403

The client is not authorized to access this resource. Ensure that the correct permissions are granted.

application/json

Schema

Schema

response-code integer
message string
error.code string

Example (from schema)

{
  "response-code": 403,
  "message": "Unauthorized access: Client is not allowed to access API",
  "error.code": "MD022"
}

500

An unexpected error occurred on the server. This might be due to a temporary issue or a problem with the request processing.

application/json

Schema

Schema

result object[]
Array [
response-code integer
status string
message string
error.code string
error string
]

Example (from schema)

{
  "result": [
    {
      "response-code": 500,
      "status": "fail",
      "message": "Internal server exception, Possible reason: Cannot invoke \"String.length()\" because \"content\" is null",
      "error.code": "MD031",
      "error": "io.vertx.core.json.jackson.DatabindCodec.createParser(DatabindCodec.java:116)\n\tat io.vertx.core.json.jackson.DatabindCodec.fromString(DatabindCodec.java:90)\n\tat io.vertx.core.json.Json.decodeValue(Json.java:83)\n\tat io.vertx.core.json.Json.decodeValue(Json.java:95)\n\tat"
    }
  ]
}

Authorization: cookie

name: cookietype: apiKeyin: cookie

• curl
• python
• go
• nodejs
• ruby
• csharp
• php
• java
• powershell

• CURL

curl -L 'https://ServerIP:PortNumber/api/v1/query/metric/histogram' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "queries": [
    {
      "aggregator": "avg",
      "data.point": "system.cpu.percent",
      "entity.type": "monitor",
      "entities": [
        83948934
      ]
    }
  ],
  "data.filter": {
    "data.filter": {
      "groups": [
        {
          "conditions": [
            {
              "operand": "network.service.instance.name",
              "operator": "contain",
              "value": "SSH"
            },
            {
              "operand": "network.service.instance.name",
              "operator": "contain",
              "value": "HTTPS"
            },
            {
              "operand": "network.service.instance.name",
              "operator": "contain",
              "value": "Mindarray"
            }
          ],
          "filter": "include",
          "operator": "or"
        },
        {
          "conditions": [
            {
              "operand": "network.service.instance.name",
              "operator": "=",
              "value": "8081 (Apache HTTP)"
            },
            {
              "operand": "network.service.ip.address",
              "operator": "=",
              "value": "127.0.0.1"
            },
            {
              "operand": "network.service.port",
              "operator": "=",
              "value": 80
            }
          ],
          "filter": "include",
          "operator": "or"
        },
        {
          "conditions": [
            {
              "operand": "network.service.ip.address",
              "operator": "=",
              "value": "172.16.15.199"
            },
            {
              "operand": "network.service.ip.address",
              "operator": "=",
              "value": "172.16.15.134"
            },
            {
              "operand": "network.service.ip.address",
              "operator": "=",
              "value": "172.16.15.123"
            }
          ],
          "filter": "exclude",
          "operator": "or"
        }
      ],
      "filter": "include",
      "operator": "or"
    }
  },
  "result.filter": {
    "conditions": [
      {
        "operand": "network.service.latency.ms.avg",
        "operator": "=",
        "value": 10
      },
      {
        "operand": "network.service.latency.ms.avg",
        "operator": "=",
        "value": 8
      },
      {
        "operand": "network.service.latency.ms.avg",
        "operator": "=",
        "value": 5
      }
    ],
    "filter": "exclude",
    "operator": "and"
  },
  "timeline": {
    "from.date": "2024/10/11",
    "from.time": "00:00:00",
    "to.date": "2024/10/11",
    "to.time": "17:00:00"
  },
  "granularity": "5 m",
  "type": "metric",
  "result.by": [
    "monitor"
  ]
}'

Request Collapse all

Base URL

https://ServerIP:PortNumber/api/v1

Auth

Security Scheme

CookieAuthBearerAuth

CookieAuth

Body required

{
  "queries": [
    {
      "aggregator": "avg",
      "data.point": "system.cpu.percent",
      "entity.type": "monitor",
      "entities": [
        83948934
      ]
    }
  ],
  "data.filter": {
    "data.filter": {
      "groups": [
        {
          "conditions": [
            {
              "operand": "network.service.instance.name",
              "operator": "contain",
              "value": "SSH"
            },
            {
              "operand": "network.service.instance.name",
              "operator": "contain",
              "value": "HTTPS"
            },
            {
              "operand": "network.service.instance.name",
              "operator": "contain",
              "value": "Mindarray"
            }
          ],
          "filter": "include",
          "operator": "or"
        },
        {
          "conditions": [
            {
              "operand": "network.service.instance.name",
              "operator": "=",
              "value": "8081 (Apache HTTP)"
            },
            {
              "operand": "network.service.ip.address",
              "operator": "=",
              "value": "127.0.0.1"
            },
            {
              "operand": "network.service.port",
              "operator": "=",
              "value": 80
            }
          ],
          "filter": "include",
          "operator": "or"
        },
        {
          "conditions": [
            {
              "operand": "network.service.ip.address",
              "operator": "=",
              "value": "172.16.15.199"
            },
            {
              "operand": "network.service.ip.address",
              "operator": "=",
              "value": "172.16.15.134"
            },
            {
              "operand": "network.service.ip.address",
              "operator": "=",
              "value": "172.16.15.123"
            }
          ],
          "filter": "exclude",
          "operator": "or"
        }
      ],
      "filter": "include",
      "operator": "or"
    }
  },
  "result.filter": {
    "conditions": [
      {
        "operand": "network.service.latency.ms.avg",
        "operator": "=",
        "value": 10
      },
      {
        "operand": "network.service.latency.ms.avg",
        "operator": "=",
        "value": 8
      },
      {
        "operand": "network.service.latency.ms.avg",
        "operator": "=",
        "value": 5
      }
    ],
    "filter": "exclude",
    "operator": "and"
  },
  "timeline": {
    "from.date": "2024/10/11",
    "from.time": "00:00:00",
    "to.date": "2024/10/11",
    "to.time": "17:00:00"
  },
  "granularity": "5 m",
  "type": "metric",
  "result.by": [
    "monitor"
  ]
}

ResponseClear

Click the Send API Request button above and see the response here!