[APIM]] Rate limit counter explanation

Author: dlepow

articles/api-management/rate-limit-by-key-policy.md

@@ -6,7 +6,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: article
-ms.date: 03/18/2024
+ms.date: 05/23/2024
 ms.author: danlep
 ---
 
@@ -42,15 +42,15 @@ To understand the difference between rate limits and quotas, [see Rate limits an
 
 | Attribute                | Description                                                                                           | Required | Default |
 | ------------------- | ----------------------------------------------------------------------------------------------------- | -------- | ------- |
-| calls               | The maximum total number of calls allowed during the time interval specified in the `renewal-period`. Policy expressions are allowed. | Yes      | N/A     |
+| calls               | The maximum total number of calls allowed for the key value during the time interval specified in the `renewal-period`. Policy expressions are allowed. | Yes      | N/A     |
 | counter-key         | The key to use for the rate limit policy. For each key value, a single counter is used for all scopes at which the policy is configured. Policy expressions are allowed.         | Yes      | N/A     |
 | increment-condition | The Boolean expression specifying if the request should be counted towards the rate (`true`). Policy expressions are allowed.        | No       | N/A     |
 | increment-count | The number by which the counter is increased per request. Policy expressions are allowed.       | No       | 1     |
 | renewal-period      | The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in `calls`. Maximum allowed value: 300 seconds. Policy expressions are allowed.                | Yes      | N/A     |
-| retry-after-header-name    | The name of a custom response header whose value is the recommended retry interval in seconds after the specified call rate is exceeded. Policy expressions aren't allowed. |  No | `Retry-After`  |
-| retry-after-variable-name    | The name of a policy expression variable that stores the recommended retry interval in seconds after the specified call rate is exceeded. Policy expressions aren't allowed. |  No | N/A  |
-| remaining-calls-header-name    | The name of a response header whose value after each policy execution is the number of remaining calls allowed for the time interval specified in the `renewal-period`. Policy expressions aren't allowed. |  No | N/A  |
-| remaining-calls-variable-name    | The name of a policy expression variable that after each policy execution stores the number of remaining calls allowed for the time interval specified in the `renewal-period`. Policy expressions aren't allowed. |  No | N/A  |
+| retry-after-header-name    | The name of a custom response header whose value is the recommended retry interval in seconds after the specified call rate is exceeded for the key value. Policy expressions aren't allowed. |  No | `Retry-After`  |
+| retry-after-variable-name    | The name of a policy expression variable that stores the recommended retry interval in seconds after the specified call rate is exceeded for the key value. Policy expressions aren't allowed. |  No | N/A  |
+| remaining-calls-header-name    | The name of a response header whose value after each policy execution is the number of remaining calls allowed for the key value in the time interval specified in the `renewal-period`. Policy expressions aren't allowed. |  No | N/A  |
+| remaining-calls-variable-name    | The name of a policy expression variable that after each policy execution stores the number of remaining calls allowed for the key value in the time interval specified in the `renewal-period`. Policy expressions aren't allowed. |  No | N/A  |
 | total-calls-header-name    | The name of a response header whose value is the value specified in `calls`. Policy expressions aren't allowed. |  No | N/A  |
 
 ## Usage
@@ -61,18 +61,19 @@ To understand the difference between rate limits and quotas, [see Rate limits an
 
 ### Usage notes
 
+* API Management uses a single counter for each `counter-key` value. The counter is updated at all scopes at which the policy is configured with that key value. If you want to configure separate counters at different scopes (for example, a specific API or product), specify different key values at the different scopes. For example, append a string that identifies the scope to the key value.
 * [!INCLUDE [api-management-self-hosted-gateway-rate-limit](../../includes/api-management-self-hosted-gateway-rate-limit.md)] [Learn more](how-to-self-hosted-gateway-on-kubernetes-in-production.md#request-throttling)
 
 
 ## Example
 
-In the following example, the rate limit of 10 calls per 60 seconds is keyed by the caller IP address. After each policy execution, the remaining calls allowed in the time period are stored in the variable `remainingCallsPerIP`.
+In the following example, the rate limit of 10 calls per 60 seconds is keyed by the caller IP address. After each policy execution, the remaining calls allowed for that caller IP address in the time period are stored in the variable `remainingCallsPerIP`.
 
 ```xml
 <policies>
     <inbound>
         <base />
-        <rate-limit-by-key  calls="10"
+        <rate-limit-by-key calls="10"
               renewal-period="60"
               increment-condition="@(context.Response.StatusCode == 200)"
               counter-key="@(context.Request.IpAddress)"