This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
The security stats API lets you view abuse and bot-related statistics over the past 14 days. There are two type of security stats:
- Tabular stats, which don't have a time dimension. Tabular stats are often
computed using an aggregation function, for example,
sum for message_count
orbot_traffic
. - Time series stats, which do have a time dimension.
Parameters in example API calls
The following sections give examples of API calls that use the security stats API. The API calls contain the following parameters:
- ORG: Your organization.
- ENV: Your environment.
- METRIC_i: A metric for the statistic. See Metrics and aggregation functions.
- AGGREGATION_i: An aggregation function for the metric. See the table below.
- DIMENSION_i: A dimension for grouping the values of the statistic.
- PAGE_SIZE: Maximum number of subcomponents returned in a single page.
time_range
: The time range for the statistics in the form"time_range": { "start_time": START_TIME, "end_time": END_TIME }
where:
- START_TIME is the start time for the time range.
- END_TIME is the end time for the time range.
START_TIME and END_TIME are of the form
"YYYY-MM-DDT00:00:00Z"
.The length of the time range can be at most 14 days, and both the start date and end date must be within the past 365 days.
Example: Query tabular security stats for an environment
A request that queries tabular stats has the following format:
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \ -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \ '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}], "dimensions": ["DIMENSION_1", "DIMENSION_2"], "page_size": PAGE_SIZE, "time_range": { "start_time": START_TIME, "end_time": END_TIME } }'
See Parameters in example API calls.
See Limitations on security stats for the maximum numbers of metrics, aggregation functions, and dimensions that can be included in a request.
Here is an example of a request that queries tabular stats:
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \ -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \ '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"}, {"metric": "bot_traffic", "aggregation": "sum"}, {"metric": "bot_first_detected", "aggregation": "min"}, {"metric": "bot_last_detected", "aggregation": "max"}], "dimensions": ["apiproxy", "bot_reason", "ax_resolved_client_ip", "ax_geo_city", "ax_geo_country", "client_id", "proxy_basepath", "proxy_pathsuffix"], "page_size": 1, "time_range": { "start_time": START_TIME, "end_time": END_TIME } }'
See the
queryTabularStats
reference page for descriptions of the request
and response.
Example: Query time series security stats for an environment
Time series APIs return time series stats for the chosen metrics, grouped by the chosen dimension.
The following call invokes time series stats for bot traffic grouped by API proxy. Since there are four proxies, this yields four sequences of time series points. The order of the points of each row match the corresponding index in the columns field.
Here is a sample request:
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \ -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \ '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}], "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE", "page_size": PAGE_SIZE, "time_range": { "start_time": START_TIME, "end_time": END_TIME } }'
See Parameters in example API calls.
See the
queryTabularStats
reference page for descriptions of the request
and response.
Example: Query incident details for abuse detection
The following example queries the details of an incident for Advanced API Security's Abuse detection. The call returns details for bot count for the developer_app for a given incident.
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \ -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d \ '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}], "dimensions": ["incident_id", "developer_app"], "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''", "page_size": 100, "time_range": { "start_time": START_TIME, "end_time": END_TIME } }'
See Parameters in example API calls.
This returns a response like the following:
{ "values": [ [ "d897d1af-51ac-4b5d-a29e-d1059d922a05", "Developer2_App1", 18353 ], [ "d897d1af-51ac-4b5d-a29e-d1059d922a05", "Developer1_App1", 18082 ] ], "columns": [ "incident_id", "developer_app", "bot_traffic" ] }
See the
queryTabularStats
reference page for descriptions of the request
and response.
Metrics and aggregation functions
The following table describes the metrics and aggregation functions available in the security stats API:
Metric |
Description | Aggregation function |
---|---|---|
bot |
The number of distinct IP addresses for detected bots over one-minute intervals. | count_distinct |
bot_first_detected |
Date and time the bot was first detected. Only available through the API. | min |
bot_last_detected |
Date and time the bot was last detected. Only available through the API. | max |
bot_traffic |
The number of messages from IP addresses of detected bots over one-minute intervals. | sum |
message_count |
Total number of API calls processed by Apigee in one-minute intervals. Note: |
sum |
response_size |
Size of the response. | average , max , min , sum |
Dimensions
Dimensions let you group metric values together based on related subsets of the data. The following table describes the dimensions that are specific to Advanced API Security reports:
Dimension | Description |
---|---|
bot_reason |
Can be any combination of the security
detection rules.
bot_reason consists of the
subset of the detection rules that the bot's traffic pattern matched. |
incident_id (preview) |
The UUID for a security incident, which is returned by a call to the Incidents API. See Example: Get details or a specific incident. |
security_action |
The security action. Possibly values are ALLOW , DENY , or
FLAG .
|
security_action_name |
The name of the security action. |
security_action_headers |
Headers that you can use to query for a flag security action. |
Note: bot_reason
and incident_id
only work with the following metrics:
bot
bot_traffic
response_size
In addition to the dimensions described above, Advanced API Security also supports the following dimensions:
access_token
access_token
api_product
apiproxy
ax_edge_execution_fault_code
ax_geo_city
ax_geo_continent
ax_geo_country
ax_geo_region
ax_isp
ax_resolved_client_ip
ax_ua_agent_version
client_id
developer
developer_app
developer_email
environment
proxy_basepath
proxy_pathsuffix
request_uri
response_status_code
target_url
useragent
Limitations on security stats
The security stats API (both tabular and time series) has the following limits:
- Maximum page size: 14400
- Maximum of 10 time series dimensions
- Maximum of 15 tabular stats dimensions
- Maximum of 5 metric aggregations.
- Maximum of 5 time series metric aggregations
- Time range: Length can be at most 14 days, and both the start date and end date must be within the past 365 days.
- The dimensions
incident_id
andbot_reason
cannot be used with the metricsmessage_count
orresponse_size
.
Comparing the security stats API and the security reports API
Both the security stats API and the security reports API return abuse and bot-related security statistics, but they have the following differences:
The security stats API is designed to view statistics for recent API traffic. Data for the security stats API goes back only 14 days, but you can view the stats immediately when you send a request.
Security stats are also displayed in the Abuse metrics view in the Apigee UI.
- The security reports API is designed to view statistics for long-running operations. To use the security scores API, you submit a job and view the results only when the job is completed. Data for the security scores API goes back one year.