This pageapplies toApigee andApigee 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.

• ORG: Your organization.
• ENV: Your environment.
• METRIC_i: A metric for the statistic. SeeMetrics 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 andEND_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          }        }'

SeeParameters in example API calls.

SeeLimitations 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 thequeryTabularStats 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 arefour proxies, this yields four sequences of time series points. The order of the points of each rowmatch 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          }        }'

SeeParameters in example API calls.

See thequeryTabularStats 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'sAbuse detection. The call returnsdetails 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          }        }'

SeeParameters 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 thequeryTabularStats reference page for descriptions of the request and response.

Metrics and aggregation functions

The following table describes the metrics and aggregation functions available inthe security stats API:

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:

Note:bot_reason andincident_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 followingdimensions:

• access_token
• api_product
• apiproxy
• app_group_app
• app_group_name
• 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
• is_filtered_out
• 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 dimensionsincident_id andbot_reason cannot be used with the metricsmessage_count orresponse_size.
• The dimensionsis_filtered_out is only supported by tabular stats, and apply to old data as well.

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 securitystatistics, 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 theAbuse metrics view in the Apigee UI.

• Thesecurity 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.