AWS CLI Command Reference

Note:

You are viewing the documentation for an older major version of the AWS CLI (version 1). To view this page for the AWS CLI version 2, click here.

We announced the upcoming end-of-support for the AWS CLI v1. For dates, additional details, and information on how to migrate, please refer to the linked announcement. For more information see the AWS CLI version 2 installation instructions and migration guide.

[ aws . wafv2 ]

get-top-path-statistics-by-traffic

Description

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

Synopsis

  get-top-path-statistics-by-traffic
--web-acl-arn <value>
--scope <value>
[--uri-path-prefix <value>]
--time-window <value>
[--bot-category <value>]
[--bot-organization <value>]
[--bot-name <value>]
--limit <value>
--number-of-top-traffic-bots-per-path <value>
[--next-marker <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--v2-debug]

Options

--web-acl-arn (string)

The Amazon Resource Name (ARN) of the web ACL for which you want to retrieve path statistics.

--scope (string)

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.

Possible values:

  • CLOUDFRONT
  • REGIONAL

--uri-path-prefix (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.

--time-window (structure)

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 -> (timestamp)

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 -> (timestamp)

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.

Shorthand Syntax:

StartTime=timestamp,EndTime=timestamp

JSON Syntax:

{
  "StartTime": timestamp,
  "EndTime": timestamp
}

--bot-category (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.

--bot-organization (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.

--bot-name (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.

--limit (integer)

The maximum number of path statistics to return. Valid values are 1 to 100.

--number-of-top-traffic-bots-per-path (integer)

The maximum number of top bots to include in the statistics for each path. Valid values are 1 to 10.

--next-marker (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.

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

Global Options

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

  • json
  • text
  • table

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

  • on
  • off
  • auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--v2-debug (boolean)

Enable AWS CLI v2 migration assistance. Prints warnings if the command would face a breaking change after swapping AWS CLI v1 for AWS CLI v2 in the current environment. Prints one warning for each breaking change detected.

Output

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.

(structure)

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 -> (structure)

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 -> (long)

The number of requests to this path within the specified time window.

Percentage -> (double)

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.

(structure)

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 -> (long)

The number of requests from this bot to the associated path within the specified time window.

Percentage -> (double)

The percentage of total requests to the associated path that came from this bot.

TotalRequestCount -> (long)

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.

(structure)

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 -> (structure)

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 -> (long)

The number of requests to this path within the specified time window.

Percentage -> (double)

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.

(structure)

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 -> (long)

The number of requests from this bot to the associated path within the specified time window.

Percentage -> (double)

The percentage of total requests to the associated path that came from this bot.