You're viewing **Apigee Edge** documentation.
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/analytics/use-analytics-api-measure-api-program-performance). info
Apigee Edge records a wide variety of
operational and business data that flows across APIs. The metrics derived from this data are
useful for operational monitoring and business monitoring. Using Edge API Analytics, you can, for
example, determine which APIs are performing well or poorly, which developers are delivering the
highest value traffic, and which apps are causing the most issues for your backend services.
To help access this metrics data easily, Edge exposes a RESTful API. You can
use the metrics API when you need to automate certain Analytics functions, such as retrieving metrics
periodically using an automation client or script. You can also use the API to build your own
visualizations in the form of custom widgets that you can embed in portals or custom apps.
To learn how to use Analytics in the API
Edge management UI see [API Analytics overview](https://docs.apigee.com/api-platform/analytics/analytics-services-overview).
> [!NOTE]
> **Note:** **Data delay interval**
> After API calls are made to proxies, it may take up to **13 minutes** for the data to appear in dashboards, custom reports, and management API calls.
## About the metrics APIs
Edge provides two metrics APIs:
- [Get metrics](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/stats)
returns metrics for an **organization and environment**
over a period of time, such as an hour, day, or week.
For example, for the previous week you want to obtain:
- The number of policy errors
- The average response time
- The total traffic
- [Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0)
returns metrics over a period of time for an org and environment **grouped by
[dimension](https://docs.apigee.com/api-platform/analytics/analytics-reference#dimensions)**.
For example, for the previous week you use dimensions to group metrics by API product, API proxy,
and developer email to obtain:
- The number of policy errors **per API product**
- The average response time **per API proxy**
- The total traffic **per developer email**
The [Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0)
API supports additional features not supported by the [Get metrics](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/stats)
API, including:
- [Sorting](https://docs.apigee.com/api-platform/analytics/use-analytics-api-measure-api-program-performance#sortingresultsbyrelativeranking)
- [Filtering](https://docs.apigee.com/api-platform/analytics/use-analytics-api-measure-api-program-performance#filteringresults)
- [Paginating](https://docs.apigee.com/api-platform/analytics/use-analytics-api-measure-api-program-performance#paginatingresults)
## About metrics API quotas
Edge enforces the following quotas on these calls. The quota is based on the backend system that
handles the call:
> [!NOTE]
> **Note:**Quotas are enforced for direct API calls, and not when using the UI.
- **Postgres**: 40 calls per minute
- **BigQuery**: 12 calls per minute
Determine the backend system that handles the call by examining the response object.
Every response object contains a `metaData` property that lists service that handled the call
in the `Source` property. For example, for Postgres:
```
{
...
"metaData": {
"errors": [],
"notices": [
"Source:Postgres",
"Table used: xxxxxx.yyyyy",
"query served by:111-222-333"
]
}
}
```
For BigQuery, the `Source` property is:
```
"Source:Big Query"
```
If you exceed the call quota, the API returns an HTTP 429 response.
## Getting metrics with the management API
The main difference between the two APIs is that [Get metrics](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/stats)
returns raw metrics for the entire org and environment, while
[Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0)
lets you group metrics by different entity types, such as API product, developer, and app.
The request URL for the [Get metrics](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/stats) API is:
```
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats
```
For the [Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0)
API, you include an additional resource to the URL after `/stats` that speciifes the desired [dimension](https://docs.apigee.com/api-platform/analytics/analytics-reference#dimensions):
```
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension
```
For example, to get metrics grouped by API proxy, you'd use the following URL to call
the management API:
```
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy
```
> [!NOTE]
> **Note:** In this topic, you get metrics for the set of Edge built-in dimensions. See [Analyze API message content using custom analytics](https://docs.apigee.com/api-platform/analytics/analyze-api-message-content-using-custom-analytics), for information on how to define and work with your own custom dimensions.
### Specifying the metrics to return
For both the
[Get metrics](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/stats) and the
[Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0)
APIs you use the `select` query parameter to specify the [metrics](https://docs.apigee.com/api-platform/analytics/analytics-reference#metrics)
to retrieve, and an optional aggregation function, in the form:
```
?select=metric
```
or:
```
?select=aggFunction(metric)
```
Where:
- [metric](https://docs.apigee.com/api-platform/analytics/analytics-reference#metrics) specifies the data you want to return. For example, the number of API requests, cache hits, or policy errors. See [metrics](https://docs.apigee.com/api-platform/analytics/analytics-reference#metrics) for a table that specifies the metric name to use with the `select` query parameter.
- aggFunction specifies the optional aggregation function run against the metric.
For example, you can use the following aggregation functions with the processing latency metric:
- `avg`: Returns the average processing latency.
- `min`: Returns the minimum processing latency.
- `max`: Returns the maximum processing latency.
- `sum`: Returns the sum of all processing latencies.
Not all metrics support all aggregation functions. The documentation on
[metrics](https://docs.apigee.com/api-platform/analytics/analytics-reference#metrics) contains a table that specifies the metric name
and the function (`sum`, `avg`, `min`, `max`) supported by the metric.
For example, to return the average number of transactions, meaning API proxy requests, per second:
```
?select=tps
```
Notice that this example does not require an aggregation function. The next example uses
an aggregation function to return the sum of cache hits:
```
?select=sum(cache_hit)
```
You can returns multiple metrics for a single API call. To get metrics for the sum of policy errors
and the average request size, set the `select` query param using a comma-separated
list of metrics:
```
?select=sum(policy_error),avg(request_size)
```
### Specifying the time period
The metrics API return data for a specified period of time. Use the `timeRange`
query parameter to specify the time period, in the form:
```
?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
```
Notice the `%20` before `HH:MM`. The `timeRange` parameter
requires a URL-encoded space character before `HH:MM`, or a `+` character,
as in: `MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM`.
For example:
```
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
```
Do not use 24:00 as the time because it wraps around to 00:00. Use 23:59 instead.
> [!NOTE]
> **Note:** For information on the length of data retention, see the [Apigee Edge plans page](https://apigee.com/api-management/#/pricing).
### Using a delimiter
To separate multiple dimensions in an API call, use a comma (`,`) as the delimiter.
For example, in the API call
```
curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day
```
the dimensions `apis` and `apps` are separated by `,`.
**Note:** Previously, there was an undocumented usage that allowed a forward slash (`/`) as the delimiter. This is no longer supported: Use a comma as the delimiter instead.
### Sample API calls
This section contains examples using the [Get metrics](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/stats) and the
[Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0)
APIs.
See [Metrics API examples](https://docs.apigee.com/api-platform/analytics/analytics-command-reference) for additional examples.
**Return the total number of calls made to your APIs for one month**
To see the total number of calls made to all APIs in your org and environment for one month, use the
[Get metrics](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/stats) API:
```
curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password
```
Sample Response:
```
{
"environments": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
"7.44944088E8"
]
}
],
"name": "prod"
}
],
...
}
```
**Return the total message count per API proxy for two days**
In this example, you return metrics for the number of requests received by all API proxies
over a two-day period. The `select` query param defines the aggregate function `sum` for the metric
`message_count` on the dimension `apiproxy`. The report returns the request message throughput
for all APIs for traffic received between the beginning of 6/20/2018 and the end of 6/21/2018, in
UTC time:
```
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password
```
Sample Response:
```
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1498003200000,
"value" : "1100.0"
} ]
} ],
"name" : "target-reroute"
} ],
"name" : "test"
} ]...
}
```
This response indicates that 1100 message were received by one API proxy called
'target-reroute' running in the test environment between the start of 6/20/2018 and the end of
6/21/2018.
> [!IMPORTANT]
> **Tip:** Note that the timestamp, `1498003200000`, is in Unix timestamp format. There are many Unix timestamp conversion tools available on the Internet that you can use to decode these timestamps.
To get metrics for other dimensions, specify a different dimension as the URI parameter. For
example, you can specify the `developer_app` dimension to retrieve metrics for
developer apps. The following API call returns the total throughput (messages received) from any apps
for the specified time interval:
```
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:password
```
Sample Response:
```
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "886.0"
}
]
}
],
"name": "Test-App"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "6645.0"
}
]
}
],
"name": "johndoe_app"
},
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1498003200000,
"value": "1109.0"
}
]
}
],
"name": "marys_app"
}
]...
}
```
## Sorting results by relative ranking
Many times when getting metrics, you only want to get results for a subset of the total set of
data. Usually, you need to get the results for the "top 10", for example, the "top 10 slowest
APIs", the "top 10 most active apps". You can do this using the `topk` query parameter
as part of the request.
> [!NOTE]
> **Note:** Sorting is only supportedby the [Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0) API.
For example you may be interested to know who your top developers are, measured by throughput,
or what your worst performers (i.e., 'top slowest') target APIs are by latency.
The `topk` (meaning 'top k' entities) enables reporting on the entities associated
with the highest value for a given metric. This enables you to filter metrics for a list of
entities that exemplify a particular condition. For example, to find which target URL was the
most error prone over the last week, the `topk` parameter is appended to the request,
with a value of `1`:
```
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
-u email:password
```
```
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(is_error)",
"values": [
{
"timestamp": 1494201600000,
"value": "12077.0"
}
]
}
],
"name": "http://api.company.com"
}
]...
}
```
The result of this request is a set of metrics that shows that the buggiest target URL is
`http://api.company.com`.
You can also use the `topk` parameter to sort for the APIs experiencing the highest
throughput. The following example retrieves metrics on the top ranked API, defined by highest
throughput in the last week:
```
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
-u email:password
```
Sample Response
```
{
"environments": [
{
"dimensions": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
{
"timestamp": 1494720000000,
"value": "5750.0"
},
{
"timestamp": 1494633600000,
"value": "5752.0"
},
{
"timestamp": 1494547200000,
"value": "5747.0"
},
{
"timestamp": 1494460800000,
"value": "5751.0"
},
{
"timestamp": 1494374400000,
"value": "5753.0"
},
{
"timestamp": 1494288000000,
"value": "5751.0"
},
{
"timestamp": 1494201600000,
"value": "5752.0"
}
]
}
],
"name": "testCache"
}
],
"name": "test"
}
]...
}
```
## Filtering results
For greater granularity, you can filter results to limit the data returned. When using
filters, you must use dimensions as filter properties.
> [!NOTE]
> **Note:** Filtering is only supportedby the [Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0) API.
For example, suppose that you need to retrieve a count of errors from backend services
filtered by the HTTP verb of the request. Your goal is find out how many POST and PUT requests
are generating errors per backend service. To do so, you use the dimension
`target_url` along with the filter `request_verb`:
```
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
-u email:password
```
Sample response:
```
{
"environments" : [
{
"dimensions" : [
{
"metrics" : [
{
"name" : "sum(is_error)",
"values" : [
{
"timestamp" : 1519516800000,
"value" : "1.0"
}
]
}
],
"name" : "testCache"
}
],
"name" : "test"
}
]...
}
```
> [!NOTE]
> **Note:** Do *not* use `/` as a shortcut for filters. For example, the following is a correct call:
>
> ```
> curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis?filter=(apis eq 'myapp')&select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day
> ```
>
> In this call, do *not* replace `apis?filter=(apis eq 'myapp')&select=` with the
> shortcut `apis/myapp?select=`.
## Paginating results
In production environments, some request to the Edge analytics API return very large data
sets. To make it easy to display large data sets in the context of a UI-based application, the
API natively supports pagination.
> [!NOTE]
> **Note:** Paginating is only supportedby the [Get metrics organized by dimensions](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/environments/%7Benv_name%7D/stats/%7Bdimension_name%7D-0) API.
To paginate results, use the `offset` and `limit` query parameters,
along with the `sortby` sorting parameter to ensure a consistent ordering of
items.
> [!NOTE]
> **Note:** When paginating results, it's important to sort results in a predictable way using the `sortby` query parameter. Without sorting, results are returned in an unpredictable order, which defeats the purpose of pagination.
>
> The `sortby` value must be the same as one used in the `select` query
> parameter. For example, if `select=sum(message_count)`, then
> `sortby=sum(message_count)`.
For example, the following request would be likely to return a large data set, since it
retrieves metrics for all errors on all APIs in the product environment for the last week.
```
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password
```
If your UI-based application can reasonably display 50 results per page, you can set the limit
to 50. Since 0 counts as the first item, the following call returns items 0-49 in descending
order (`sort=DESC` is the default).
```
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
-u email:password
```
For the second 'page' of results, use the offset query parameter, as follows. Note that the
limit and offset are identical. That's because 0 counts as the first item. With a limit of 50 and
an offset of 0, items 0-49 are returned. With an offset of 50, items 50-99 are returned.
```
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
-u email:password
```