Metrics Query API

You can use the Metrics Query API to retrieve various metrics for the API Portal. The Custom Report page in the API Portal uses this API to retrieve business insights that are visualized using Portal UI. Integrating with the Metrics Query API allows you to create your own custom data visualizations.
In this article, you can understand the following:
3
Request Fields
This API includes the following request input fields:
  • metrics
    : Specifies the metrics parameters. This is a mandatory parameter.
  • timeRange
    : Specifies the time related parameters
  • filter
    : Specifies the filter dimensions
  • groupBy
    : Specifies the group-by dimensions
Metrics
Parameter Name
Value
Default Value
Description
type
hits | latency
-
Specifies the type of metrics. This is a mandatory parameter.
aggregation
count | avg
-
Specifies the type of aggregation. This is a mandatory parameter.
Time Range
Parameter Name
Value
Valid Values
Default Value
Description
type
interval | period
-
period
Specifies the type of time range filter.
interval (for type interval)
startDate/endDate
-
-
Species the time interval using start date and end date.
period (for type period)
Period
xD, xH
x - integer value
H - hours, D - Days
7D
Species the time period in the following format:
numValue plus timeMetric
1D
denotes 1 day,
24H
denotes 24 hours
aggregation
hour | day | week | month
-
all
Specifies the time aggregation.
Filter
Parameter Name
Value
Default Value
Description
type
and | or | selector | in | bound | regex
-
Specifies the type of the filter.
dimension
apiId | appId | orgId | respCode | uri | gatewayServerId
-
Specifies the dimension.
and | or Filter
Parameter Name
Value
Default Value
Description
type
and | or
-
Specifies the type of the filter.
fields
[ <filter1>, <filter2> ]
-
Specifies the list of filters.
selector Filter
Parameter Name
Value
Default Value
Description
type
selector
-
Specifies the type of filter. This is a mandatory parameter.
dimension
apiId | appId | orgId | respCode | uri | gatewayServerId
-
Specifies the dimension. This is a mandatory parameter.
value
<value>
-
Specifies the value. This is a mandatory parameter.
in Filter
Parameter Name
Value
Default Value
Description
type
in
-
Specifies the type of the filter. This is a mandatory parameter.
dimension
apiId | appId | orgId | respCode | uri | gatewayServerId
-
Specifies the dimension. This is a mandatory parameter.
value
[ <value1>, <value2> ]
-
Specifies the list of values. This is a mandatory parameter.
bound Filter
Parameter Name
Value
Default Value
Description
type
range
-
Specifies the GroupBy type. This is a mandatory parameter.
dimension
respCode
-
Specifies the dimension. This is a mandatory parameter.
lower
<lower>
-
Specifies the lower bound for the filter. This is a mandatory parameter.
upper
<upper>
-
Specifies the upper bound for the filter. This is a mandatory parameter.
lowerStrict
true | false
false
Specifies if strict comparison on the lower bound (">" instead of ">=") needs to be performed.
upperStrict
true | false
false
Specifies if strict comparison on the upper bound ("<" instead of "<=") needs to be performed.
GroupBy
Parameter Name
Value
Default Value
Description
groupBy
[ <groupBy1>, <groupBy2> ]
-
Specifies the groupBy filters.
GroupBy Default
Parameter Name
Value
Default Value
Description
type
default
-
Specifies the type of the groupBy filter.
dimension
apiId | appId | orgId | respCode | uri | gatewayServerId
-
Specifies the dimension.
GroupBy Top
Parameter Name
Value
Default Value
Description
type
top
-
Specifies the type of the groupBy filter.
dimension
apiId | appId | orgId | respCode | uri | gatewayServerId
-
Specifies the dimension.
limit
<limit>
-
Indicates the limit.
GroupBy Range
Parameter Name
Value
Default Value
Description
type
range
-
Specifies the type of the groupBy filter.
dimension
respCode
-
Specifies the dimension.
ranges
[ <range1>, <range2> ]
-
Specifies the ranges.
Ranges
Parameter Name
Value
Default Value
Description
from
<from>
-
Specifies the starting range value.
to
<to>
-
Specifies the ending range value.
name
<name>
%dTO%d
(Optional) Specifies the user defined name for respCode grouping.
GroupBy Pattern
Parameter Name
Value
Default Value
Description
type
pattern
-
Specifies the type of GroupBy filter.
dimension
uri
-
Specifies the dimension of the GroupBy filter.
patterns
[ <pattern1>, <pattern2> ]
-
Specifies the list of patterns. It matches the specified dimension with the given pattern.
Patterns
Parameter Name
Value
Default Value
Description
value
<pattern>
-
Specifies the grouping pattern.
[d]
- indicates any number; place it anywhere in the pattern.
eg: /portal/api/[d] , /porta/api[d]/test
[w]
- indicates any word; place it anywhere in the pattern.
eg: /portal/[w]/test
[x]
- matches for anything. Place it
only
at the end of the pattern.
eg: /portal/api/[x]
name
<name>
-
(Optional) Specifies name for the grouping pattern.
Example Request:
{ "metrics": { "type": "hits|latency", "aggregation": "count|avg" }, "timeRange": { "type": "interval|period", "interval": "1999-12-31T16:00:00/2999-12-31T16:00:00", "period": "numValue plus timeMetric Ex. 1D -> 1day, 24H -> 24hours", "aggregation": "hour|day|week|month" }, "filter": { "type": "and|or", "fields": [{ "type": "selector", "dimension": "appId", "value": "" }, { "type": "in", "dimension": "apiId", "values": [ "" ] }, { "type": "bound", "dimension": "respCode", "lower": "400", "upper": "600", "lowerStrict": false, "upperStrict": true }, { "type": "regex", "dimension": "uri", "pattern": { "value":<pattern> } } ] }, "groupBy": [{ "type": "default" "dimension": "apiId|appId|orgId|gatewayServerId|uri|respCode", }, { "type": "top", "dimension": "apiId|appId|orgId|gatewayServerId|uri|respCode", "limit": "3" }, { "type": "pattern", "dimension": "uri", "patterns": [{ "value": "uriPattern1", "name":"pattern_name" }] }, { "type": "range", "dimension": "respCode", "ranges": [{ "name":"", "from": "", "to": "" }, { "name":"", "from": "", "to": "" } ] } ] }
Response Fields
You can view the holistic picture when data is not time-bucketed in the Request input fields. When you use Time Range filters, you can view the response trends.
Parameter Name
Value
query
Specifies the response query.
data
Specifies the response data.
Example Response:
{ "query": {}, "data": [{ "<dimension>": "<value>", "<aggregation>": "<value>", "buckets": [{ "<aggregation>": "<value>", "date": "<DATE_1>" }, { "<aggregation>": "<value>", "date": "<DATE_2>" }] } ] }
Examples
Total Hits for Default Time Range (Last 7 days)
Request:
{ "metrics": { "type": "hits", "aggregation": "count" } }
Response:
{ "query": { "startDate": "2020-02-28T00:00:00", "endDate": "2020-03-05T10:34:47", "period": "7D(default)" }, "data": [ { "count": 373741.0 } ] }
Hits for Period (no aggregation) with Filter
Request:
{ "metrics": { "type": "hits", "aggregation": "count" }, "timeRange": { "type": "period", "period": "7D" }, "filter": { "type": "and", "fields": [ { "dimension": "gatewayServerId", "type": "in", "values": [ "40f30e9b-0e90-4736-8daf-684d7922b4a4" ] } ] } }
Response:
{ "query": { "startDate": "2020-02-28T00:00:00", "endDate": "2020-03-05T11:25:54", "period": "7D" }, "data": [ { "count": 186869.0 } ] }
Hits with Dynamic Time Range (Last 7 days) by Day
Request:
{ "metrics": { "type": "hits", "aggregation": "count" }, "timeRange": { "type": "period", "period": "7D", "aggregation": "day" } }
Response:
{ "query": { "startDate": "2020-02-28T00:00:00", "endDate": "2020-03-05T10:36:08", "period": "7D", "aggregation": "day" }, "data": [{ "count": 373741.0, "buckets": [{ "date": "2020-03-04T00:00:00.000Z", "count": 49581.0 }, { "date": "2020-03-03T00:00:00.000Z", "count": 65143.0 }, { "date": "2020-03-02T00:00:00.000Z", "count": 64844.0 }, { "date": "2020-03-01T00:00:00.000Z", "count": 64337.0 }, { "date": "2020-02-29T00:00:00.000Z", "count": 64676.0 }, { "date": "2020-02-28T00:00:00.000Z", "count": 65160.0 }] }] }
Top 3 APIs by API (filter errors) for a Dynamic Time Period (Last 7 days) Without any Time-grouping
Request:
{ "filter": { "dimension": "respCode", "lower": 400, "lowerStrict": true, "type": "bound", "upper": 600, "upperStrict": false }, "groupBy": [ { "dimension": "apiId", "type": "default" }, { "dimension": "appId", "limit": 3, "type": "top" } ], "metrics": { "aggregation": "count", "type": "hits" }, "timeRange": { "period": "7D", "type": "period" } }
Response:
{ "query": { "startDate": "2020-02-28T00:00:00", "endDate": "2020-03-05T11:21:22", "period": "7D" }, "data": [ { "apiName": "Demo API 12a08972", "apiId": "faf3dd69-ed20-449c-abe7-84ae7a95bdef", "count": 1895 }, { "apiName": "Demo API 7a46de4a", "apiId": "dfc4df78-98ab-4253-b27d-b4b0b1be39f9", "count": 1843 }, { "apiName": "Demo API 53bcbe3e", "apiId": "9e4b1bd6-0e81-4da7-83b0-dd45c50d2e73", "count": 1807 } ] }
Hits with Static Time Range by Week with
and
,
or
,
in,
and
bound
Dimensional Filters
Request:
{ "metrics": { "type": "hits", "aggregation": "count" }, "timeRange": { "type": "interval", "interval": "2020-02-11T00:00:00/2020-03-05T23:59:59", "aggregation": "week" }, "filter": { "type": "and", "fields": [ { "dimension": "apiId", "type": "in", "values": [ "c9e29c47-4ac5-4464-b511-3aec4de99c89", "3e80f77d-d99d-40fc-8bf8-7a8f4ee09aa8" ] }, { "type": "or", "fields": [ { "type": "bound", "dimension": "respCode", "lower": 200, "upper": 299, "lowerStrict": false, "upperStrict": true }, { "type": "bound", "dimension": "respCode", "lower": 300, "upper": 399, "lowerStrict": false, "upperStrict": true } ] } ] } }
Response:
{ "query": { "startDate": "2020-02-11T00:00:00", "endDate": "2020-03-05T23:59:59", "aggregation": "week" }, "data": [ { "count": 230507.0, "buckets": [ { "date": "2020-03-02T00:00:00.000Z", "count": 27943.0 }, { "date": "2020-02-24T00:00:00.000Z", "count": 70166.0 }, { "date": "2020-02-17T00:00:00.000Z", "count": 71165.0 }, { "date": "2020-02-10T00:00:00.000Z", "count": 61233.0 } ] } ] }
Hits with Dynamic Time Range with Dimensional Filters and groupBy (Default and URI Pattern)
Request:
{ "metrics": { "type": "hits", "aggregation": "count" }, "timeRange": { "type": "period", "period": "3D", "aggregation": "day" }, "filter": { "dimension": "respCode", "type": "in", "values": [ "200", "400" ] }, "groupBy": [ { "type": "default", "dimension": "respCode" }, { "type": "pattern", "dimension": "uri", "patterns": [ { "type": "regex", "value": "/accounts/v1/[d]/transactions[x]", "name": "Transaction" }, { "type": "regex", "value": "/account[x]", "name": "Account" } ] } ] }
Response:
{ "query": { "startDate": "2020-03-03T00:00:00", "endDate": "2020-03-05T10:51:48", "period": "3D", "aggregation": "day" }, "data": [ { "uri": "Transaction", "respCode": "200", "count": 34375.0, "buckets": [ { "date": "2020-03-04T00:00:00.000Z", "count": 15027.0 }, { "date": "2020-03-03T00:00:00.000Z", "count": 19348.0 } ] }, { "uri": "Account", "respCode": "200", "count": 17259.0, "buckets": [ { "date": "2020-03-04T00:00:00.000Z", "count": 7321.0 }, { "date": "2020-03-03T00:00:00.000Z", "count": 9938.0 } ] }, { "uri": "Transaction", "respCode": "400", "count": 1920.0, "buckets": [ { "date": "2020-03-04T00:00:00.000Z", "count": 842.0 }, { "date": "2020-03-03T00:00:00.000Z", "count": 1078.0 } ] }, { "uri": "Account", "respCode": "400", "count": 951.0, "buckets": [ { "date": "2020-03-04T00:00:00.000Z", "count": 415.0 }, { "date": "2020-03-03T00:00:00.000Z", "count": 536.0 } ] } ] }
Latency for Dynamic Time Range (Last 3 Days) by Day with Dimensional Filters and Multiple groupBy (Top and Default)
Request:
{ "metrics": { "type": "hits", "aggregation": "count" }, "timeRange": { "type": "period", "period": "3D", "aggregation": "day" }, "filter": { "type": "and", "fields": [ { "dimension": "appId", "type": "in", "values": [ "acbc4c5c-ec1d-4196-88bc-ef09c3d95030" ] }, { "dimension": "respCode", "type": "in", "values": [ "200" ] }, { "type": "or", "fields": [ { "type": "regex", "dimension": "uri", "pattern": { "type": "regex", "value": "/account[x]", "name": "Account" } } ] } ] }, "groupBy": [ { "dimension": "apiId", "type": "top", "limit": 2 }, { "type": "default", "dimension": "appId" }, { "type": "default", "dimension": "respCode" } ] }
Response:
{ "query": { "startDate": "2020-03-03T00:00:00", "endDate": "2020-03-05T10:44:51", "period": "3D", "aggregation": "day" }, "data": [ { "apiName": "Demo API 612461", "apiId": "0df96035-3ee6-40e5-adfa-81f2efda86e6", "appName": "Demo Application 297293", "appId": "acbc4c5c-ec1d-4196-88bc-ef09c3d95030", "respCode": "200", "count": 425.0, "buckets": [ { "date": "2020-03-04T00:00:00.000Z", "count": 170.0 }, { "date": "2020-03-03T00:00:00.000Z", "count": 255.0 } ] }, { "apiName": "Demo API 665797", "apiId": "9ea73d60-af28-449f-8531-040df19cab59", "appName": "Demo Application 297293", "appId": "acbc4c5c-ec1d-4196-88bc-ef09c3d95030", "respCode": "200", "count": 423.0, "buckets": [ { "date": "2020-03-04T00:00:00.000Z", "count": 179.0 }, { "date": "2020-03-03T00:00:00.000Z", "count": 244.0 } ] } ] }
Latency for Dynamic Time Range (Last 365 Days) by Month Grouped by Response Code Ranges
Request:
{ "groupBy": [ { "dimension": "respCode", "ranges": [ { "from": "200", "to": "299", "name": "Success Responses" }, { "from": "400", "to": "499", "name": "Client Error Responses" }, { "from": "500", "to": "599", "name": "Server Error Responses" } ], "type": "range" }, { "dimension": "appId", "limit": 3, "type": "top" } ], "metrics": { "aggregation": "count", "type": "hits" }, "timeRange": { "aggregation": "month", "period": "365D", "type": "period" } }
Response:
{ "query": { "startDate": "2019-03-07T00:00:00", "endDate": "2020-03-05T11:31:54", "period": "365D", "aggregation": "month" }, "data": [ { "appName": "", "appId": "", "respCode": "Success Responses", "count": 114211, "buckets": [ { "date": "2020-03-01T00:00:00.000Z", "count": 12517 }, { "date": "2020-02-01T00:00:00.000Z", "count": 101694 } ] }, { "appName": "Demo Application d4d6d01c", "appId": "9417bc12-048b-4f84-980e-62e420a988da", "respCode": "Success Responses", "count": 56873, "buckets": [ { "date": "2020-03-01T00:00:00.000Z", "count": 6294 }, { "date": "2020-02-01T00:00:00.000Z", "count": 50579 } ] }, { "appName": "Demo Application 65e3e69c", "appId": "36f618f5-cce3-40c1-8695-8712f3e26a99", "respCode": "Success Responses", "count": 56831, "buckets": [ { "date": "2020-03-01T00:00:00.000Z", "count": 6402 }, { "date": "2020-02-01T00:00:00.000Z", "count": 50429 } ] }, { "appName": "", "appId": "", "respCode": "Client Error Responses", "count": 12671, "buckets": [ { "date": "2020-03-01T00:00:00.000Z", "count": 1392 }, { "date": "2020-02-01T00:00:00.000Z", "count": 11279 } ] }, { "appName": "Demo Application d4d6d01c", "appId": "9417bc12-048b-4f84-980e-62e420a988da", "respCode": "Client Error Responses", "count": 6316, "buckets": [ { "date": "2020-03-01T00:00:00.000Z", "count": 689 }, { "date": "2020-02-01T00:00:00.000Z", "count": 5627 } ] }, { "appName": "Demo Application 65e3e69c", "appId": "36f618f5-cce3-40c1-8695-8712f3e26a99", "respCode": "Client Error Responses", "count": 6308, "buckets": [ { "date": "2020-03-01T00:00:00.000Z", "count": 686 }, { "date": "2020-02-01T00:00:00.000Z", "count": 5622 } ] } ] }