Security stats API

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 or bot_traffic.
Time series stats, which do have a time dimension.

Note: Bot detection has a processing delay of around 15 to 20 minutes on average.

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: `message_count` cannot be used with other metrics in the same report.	`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
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 and bot_reason cannot be used with the metrics message_count or response_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.