API Usage Analytics (GQL)

Use the GraphQL Platform API to obtain aggregated statistics for calls to your APIs.

❗️

This content has moved

See API Traffic Analytics (GQL).

Summary

The GraphQL Platform API exposes a useful query, named calculatedStatistics, for extracting key API consumer metrics using different aggregation functions. In the Hub, this endpoint is used to build the analytics widget statistics on top of the line chart found in the Developer Dashboard (Apps). It could also be used to provide aggregated statistics useful to API providers and admins.

985

The calculatedStatistics query is used to populate this data in the Developer Dashboard (Apps).

Results can be narrowed down by:

  • API
  • Endpoint
  • App

Given a date range and resolution, the API response can include the following statistics:

AggregationVolumeErrorsLatency
TotalThe total number of requests (requeststotal) within the $fromDate to $toDate range (this will always be the same, regardless of the resolution).The total number of error responses (errorstotal) within the given date range (this will always be the same, regardless of the resolution).Not applicable
MaximumThe maximum number of requests (requestsmax) during a single resolution window within the given date range. For example, in a one month date range with a resolution set to "day", this value represents the number of requests for the day of the month with the most requests.The highest error rate (errorsmax) during a single resolution window within the given date range. For example, in a one month date range with a resolution set to "day", if the worst day of the month experienced an error rate of 30%, this value will be 0.3.The API response with the highest latency (in milliseconds) (latencymax) within the given date range (this will always be the same, regardless of the resolution).
MinimumThe minimum number of requests (requestsmin) during a single resolution window within the given date range. For example, in a one month date range with a resolution set to "day", this value represents the number of requests for the day of the month with the least number of requests.The lowest error rate (errorsmin) during a single resolution window within the given date range. For example, in a one month date range with a resolution set to "day", if the best day of the month experienced an error rate of 1%, this value will be 0.01.The API response with the lowest latency (latencymin) within the given date range (this will always be the same, regardless of the resolution).
AverageThe average number of requests (requestsavg) during a single resolution window within the given date range. For example, in a one month date range with a resolution set to "day", this value represents the average number of daily requests.The ratio (errorsavg) obtained by dividing the errorstotal by the requeststotal for the given date range (this will always be the same, regardless of the resolution). Multiplying this value by 100 gives the percentage of requests for the date range that resulted in errors.The average latency (latencyavg) in milliseconds for the given date range (this will always be the same, regardless of the resolution).
MedianNot applicable.The median error rate (errorsmedian) during each resolution window within the given date range. For example, in a one month date range with a resolution set to "day", if half of the days had error rates above 5% and half had error rates below 5%, this value will be 0.05.The median latency (latencymedian) in milliseconds for the given date range (this will always be the same, regardless of the resolution).

Query variables

The following variables are supported.

NameTypeMandatoryExample
apiIds[string]Yes (though "" represents all APIs)[""]
["api_04849dbb-4515-4dd3-899e-420e9af8076d",
"api_05433514-c272-4a59-a4f1-6cd281032c1a"]
fromDatestringYes"2022-12-06", "2022-12-06T08:06:18.548Z"
toDatestringYes"2023-01-05", "2023-01-05T08:06:18.549Z"
resolutionenumNo (defaults to "minutes")“seconds”, “minutes”, "hours”, “days”
projectIds (apps)[string]No[“62c43f324ce2d82497981553”] For details on obtaining this value, see this page. A value of [] means that calls from all apps by all consumers will be included, returning data for all calls made to the API(s) during the period (useful for API providers and admins).
endpoints[string]No["apiendpoint_e564e317-3183-48a2-b02f-abeafc465d7b”] For details on obtaining this value, see this page. [] represents all endpoints.

Example query and response

Below is an example of querying statistics for the last 30 days, with a daily resolution, for all API IDs, for all endpoints, and for all API consumers. The third tab demonstrates what the response for such a query would look like.

query calculatedStatistics($apiIds: [String]!, $fromDate: String!, $toDate: String!, $resolution: String, $timeOffset: Int) {
	calculatedStatistics(apiIds: $apiIds  fromDate: $fromDate toDate: $toDate resolution: $resolution timeOffset: $timeOffset) {
		requeststotal
		requestsmax
		requestsmin
		requestsavg
		requeststps
		errorsavg
		errorsmedian
		errorsmax
		errorsmin
		errorstotal
		latencyavg
		latencymedian
		latencymax
		latencymin
	}
}
{
    "apiIds": [""],
    "fromDate": "2022-12-06T08:06:18.548Z",
    "toDate": "2023-01-05T08:06:18.549Z",
    "resolution": "days",
    "timeOffset": 0
}
{
    "data": {
        "calculatedStatistics": {
            "requeststotal": 2735996208,
            "requestsmax": 127399610,
            "requestsmin": 40089284,
            "requestsavg": 91199873.6,
            "requeststps": 1055.55,
            "errorsavg": 0.03,
            "errorsmedian": 0.03,
            "errorsmax": 0.06,
            "errorsmin": 0.02,
            "errorstotal": 84327307,
            "latencyavg": 1203.03,
            "latencymedian": 486,
            "latencymax": 75919269,
            "latencymin": 0,
        }
    }
}