API Usage Analytics (GQL)
Use the GraphQL Platform API to obtain aggregated statistics for calls to your APIs.
This content has moved
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.
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:
| Aggregation | Volume | Errors | Latency |
|---|---|---|---|
| Total | The 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 |
| Maximum | The 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). |
| Minimum | The 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). |
| Average | The 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). |
| Median | Not 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.
| Name | Type | Mandatory | Example |
|---|---|---|---|
| apiIds | [string] | Yes (though "" represents all APIs) | [""] ["api_04849dbb-4515-4dd3-899e-420e9af8076d", "api_05433514-c272-4a59-a4f1-6cd281032c1a"] |
| fromDate | string | Yes | "2022-12-06", "2022-12-06T08:06:18.548Z" |
| toDate | string | Yes | "2023-01-05", "2023-01-05T08:06:18.549Z" |
| resolution | enum | No (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,
}
}
}
Updated 8 months ago