2026/02/25 - AWS WAFV2 - 1 new api methods
Changes AWS WAF now supports GetTopPathStatisticsByTraffic that provides aggregated statistics on the top URI paths accessed by bot traffic. Use this operation to see which paths receive the most bot traffic, identify the specific bots accessing them, and filter by category, organization, or bot name.
Retrieves aggregated statistics about the top URI paths accessed by bot traffic for a specified web ACL and time window. You can use this operation to analyze which paths on your web application receive the most bot traffic and identify the specific bots accessing those paths. The operation supports filtering by bot category, organization, or name, and allows you to drill down into specific path prefixes to view detailed URI-level statistics.
See also: AWS API Documentation
Request Syntax
client.get_top_path_statistics_by_traffic(
WebAclArn='string',
Scope='CLOUDFRONT'|'REGIONAL',
UriPathPrefix='string',
TimeWindow={
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1)
},
BotCategory='string',
BotOrganization='string',
BotName='string',
Limit=123,
NumberOfTopTrafficBotsPerPath=123,
NextMarker='string'
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the web ACL for which you want to retrieve path statistics.
string
[REQUIRED]
Specifies whether the web ACL is for an Amazon Web Services CloudFront distribution or for a regional application. A regional application can be an Application Load Balancer, an AppSync GraphQL API, an Amazon Cognito user pool, an Amazon Web Services App Runner service, or an Amazon Web Services Verified Access instance.
string
A URI path prefix to filter the results. When you specify this parameter, the operation returns statistics for individual URIs within the specified path prefix. For example, if you specify /api, the response includes statistics for paths like /api/v1/users and /api/v2/orders. If you don't specify this parameter, the operation returns top-level path statistics.
dict
[REQUIRED]
The time window for which you want to retrieve path statistics. The time window must be within the data retention period for your web ACL.
StartTime (datetime) -- [REQUIRED]
The beginning of the time range from which you want GetSampledRequests to return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator, Z. For example, "2016-09-27T14:50Z". You can specify any time range in the previous three hours.
EndTime (datetime) -- [REQUIRED]
The end of the time range from which you want GetSampledRequests to return a sample of the requests that your Amazon Web Services resource received. You must specify the times in Coordinated Universal Time (UTC) format. UTC format includes the special designator, Z. For example, "2016-09-27T14:50Z". You can specify any time range in the previous three hours.
string
Filters the results to include only traffic from bots in the specified category. For example, you can filter by ai to see only AI crawler traffic, or search_engine to see only search engine bot traffic. When you apply this filter, the Source field is populated in the response.
string
Filters the results to include only traffic from bots belonging to the specified organization. For example, you can filter by openai or google. When you apply this filter, the Source field is populated in the response.
string
Filters the results to include only traffic from the specified bot. For example, you can filter by gptbot or googlebot. When you apply this filter, the Source field is populated in the response.
integer
[REQUIRED]
The maximum number of path statistics to return. Valid values are 1 to 100.
integer
[REQUIRED]
The maximum number of top bots to include in the statistics for each path. Valid values are 1 to 10.
string
When you request a list of objects with a Limit setting, if the number of objects that are still available for retrieval exceeds the limit, WAF returns a NextMarker value in the response. To retrieve the next batch of objects, provide the marker from the prior call in your next request.
dict
Response Syntax
{
'PathStatistics': [
{
'Source': {
'BotCategory': 'string',
'BotOrganization': 'string',
'BotName': 'string'
},
'Path': 'string',
'RequestCount': 123,
'Percentage': 123.0,
'TopBots': [
{
'BotName': 'string',
'RequestCount': 123,
'Percentage': 123.0
},
]
},
],
'TotalRequestCount': 123,
'NextMarker': 'string',
'TopCategories': [
{
'Source': {
'BotCategory': 'string',
'BotOrganization': 'string',
'BotName': 'string'
},
'Path': 'string',
'RequestCount': 123,
'Percentage': 123.0,
'TopBots': [
{
'BotName': 'string',
'RequestCount': 123,
'Percentage': 123.0
},
]
},
]
}
Response Structure
(dict) --
PathStatistics (list) --
The list of path statistics, ordered by request count. Each entry includes the path, request count, percentage of total traffic, and the top bots accessing that path.
(dict) --
Statistics about bot traffic to a specific URI path, including the path, request count, percentage of total traffic, and the top bots accessing that path.
Source (dict) --
Information about the bot filter that was applied to generate these statistics. This field is only populated when you filter by bot category, organization, or name.
BotCategory (string) --
The bot category that was used to filter the results. For example, ai or search_engine.
BotOrganization (string) --
The bot organization that was used to filter the results. For example, OpenAI or Google.
BotName (string) --
The bot name that was used to filter the results. For example, gptbot or googlebot.
Path (string) --
The URI path. For example, /api/ or /api/v1/users.
RequestCount (integer) --
The number of requests to this path within the specified time window.
Percentage (float) --
The percentage of total requests that were made to this path.
TopBots (list) --
The list of top bots accessing this path, ordered by request count. The number of bots included is determined by the NumberOfTopTrafficBotsPerPath parameter in the request.
(dict) --
Statistics about a specific bot's traffic to a path, including the bot name, request count, and percentage of traffic.
BotName (string) --
The name of the bot. For example, gptbot or googlebot.
RequestCount (integer) --
The number of requests from this bot to the associated path within the specified time window.
Percentage (float) --
The percentage of total requests to the associated path that came from this bot.
TotalRequestCount (integer) --
The total number of requests that match the query criteria within the specified time window.
NextMarker (string) --
When you request a list of objects with a Limit setting, if the number of objects that are still available for retrieval exceeds the limit, WAF returns a NextMarker value in the response. To retrieve the next batch of objects, provide the marker from the prior call in your next request.
TopCategories (list) --
Category-level aggregations for visualizing bot category to path relationships. This field is only populated when no bot filters are applied to the request. Each entry includes the bot category and the paths accessed by bots in that category.
(dict) --
Statistics about bot traffic to a specific URI path, including the path, request count, percentage of total traffic, and the top bots accessing that path.
Source (dict) --
Information about the bot filter that was applied to generate these statistics. This field is only populated when you filter by bot category, organization, or name.
BotCategory (string) --
The bot category that was used to filter the results. For example, ai or search_engine.
BotOrganization (string) --
The bot organization that was used to filter the results. For example, OpenAI or Google.
BotName (string) --
The bot name that was used to filter the results. For example, gptbot or googlebot.
Path (string) --
The URI path. For example, /api/ or /api/v1/users.
RequestCount (integer) --
The number of requests to this path within the specified time window.
Percentage (float) --
The percentage of total requests that were made to this path.
TopBots (list) --
The list of top bots accessing this path, ordered by request count. The number of bots included is determined by the NumberOfTopTrafficBotsPerPath parameter in the request.
(dict) --
Statistics about a specific bot's traffic to a path, including the bot name, request count, and percentage of traffic.
BotName (string) --
The name of the bot. For example, gptbot or googlebot.
RequestCount (integer) --
The number of requests from this bot to the associated path within the specified time window.
Percentage (float) --
The percentage of total requests to the associated path that came from this bot.