---
title: MappedThrottlingPolicy
description: Configure MappedThrottlingPolicy in PingGateway to map different throttling rates to request groups based on expression evaluation
component: pinggateway
version: 2026
page_id: pinggateway:reference:MappedThrottlingPolicy
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/MappedThrottlingPolicy.html
revdate: 2025-10-15T18:45:22Z
section_ids:
  MappedThrottlingPolicy-usage: Usage
  MappedThrottlingPolicy-properties: Properties
  example-throttling-mapped: Example of a mapped throttling policy
  MappedThrottlingPolicy-moreinfo: More information
---

# MappedThrottlingPolicy

Maps different throttling rates to different groups of requests, according to the evaluation of `throttlingRateMapper`.

## Usage

```json
{
    "name": string,
    "type": "ThrottlingFilter",
    "config": {
        "requestGroupingPolicy": runtime expression<string>,
        "throttlingRatePolicy": {
            "type": "MappedThrottlingPolicy",
            "config": {
                "throttlingRateMapper": runtime expression<string>,
                "throttlingRatesMapping": {
                    "mapping1": {
                        "numberOfRequests": configuration expression<number>,
                        "duration": configuration expression<duration>
                    },
                    "mapping2": {
                        "numberOfRequests": configuration expression<number>,
                        "duration": configuration expression<duration>
                    }
                },
                "defaultRate": {
                    "numberOfRequests": configuration expression<number>,
                    "duration": configuration expression<duration>
                }
            }
        }
    }
}
```

## Properties

* `"throttlingRateMapper"`: *runtime expression<[string](preface.html#definition-string)>, required*

  An expression to categorize requests for mapping to a throttling rate in the `throttlingRatesMapping`.

  If this parameter is null or doesn't match any specified mappings, the default throttling rate is applied.

* `"throttlingRatesMapping"`: *[object](preface.html#definition-object), required*

  A map of throttling rate by request group. Requests are categorized into groups by the evaluation of the expression `"throttlingRateMapper"`.

  * `"mapping1"` and `"mapping2"`: *string, required*

    The evaluation of the expression `"throttlingRateMapper"`.

    The number of mappings isn't limited to two.

- `"numberOfRequests"`: *configuration expression\<integer>, required*

  The number of requests allowed through the filter in the time specified by `"duration"`.

* `"duration"`: *configuration expression<[duration](preface.html#definition-duration)>, required*

  A time interval during which the number of requests passing through the filter is counted.

* `"defaultRate"`: *[object](preface.html#definition-object), required*

  The default throttling rate to apply if the evaluation of the expression `"throttlingRateMapper"` is null or isn't mapped to a throttling rate.

- `"numberOfRequests"`: *configuration expression\<integer>, required*

  The number of requests allowed through the filter in the time specified by `"duration"`.

* `"duration"`: *configuration expression<[duration](preface.html#definition-duration)>, required*

  A time interval during which the number of requests passing through the filter is counted.

## Example of a mapped throttling policy

In the following example, requests from users with different statuses are mapped to different throttling rates.

Learn how to set up and test this example in [Configure mapped throttling](../gateway-guide/throttling.html#throttling-mapped).

```json
{
  "name": "00-throttle-mapped",
  "baseURI": "https://app.example.com:8444",
  "condition": "${find(request.uri.path, '^/home/throttle-mapped')}",
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "url": "http://am.example.com:8088/openam/"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "OAuth2ResourceServerFilter-1",
          "type": "OAuth2ResourceServerFilter",
          "config": {
            "scopes": [
              "mail",
              "employeenumber"
            ],
            "requireHttps": false,
            "accessTokenResolver": {
              "name": "token-resolver-1",
              "type": "TokenIntrospectionAccessTokenResolver",
              "config": {
                "amService": "AmService-1",
                "providerHandler": {
                  "type": "Chain",
                  "config": {
                    "filters": [
                      {
                        "type": "HttpBasicAuthenticationClientFilter",
                        "config": {
                          "username": "ig_agent",
                          "passwordSecretId": "agent.secret.id",
                          "secretsProvider": "SystemAndEnvSecretStore-1"
                        }
                      }
                    ],
                    "handler": "ForgeRockClientHandler"
                  }
                }
              }
            }
          }
        },
        {
          "name": "ThrottlingFilter-1",
          "type": "ThrottlingFilter",
          "config": {
            "requestGroupingPolicy": "${contexts.oauth2.accessToken.info.mail}",
            "throttlingRatePolicy": {
              "name": "MappedPolicy",
              "type": "MappedThrottlingPolicy",
              "config": {
                "throttlingRateMapper": "${contexts.oauth2.accessToken.info.status}",
                "throttlingRatesMapping": {
                  "gold": {
                    "numberOfRequests": 6,
                    "duration": "10 s"
                  },
                  "silver": {
                    "numberOfRequests": 3,
                    "duration": "10 s"
                  },
                  "bronze": {
                    "numberOfRequests": 1,
                    "duration": "10 s"
                  }
                },
                "defaultRate": {
                  "numberOfRequests": 1,
                  "duration": "10 s"
                }
              }
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}
```

Source: [00-throttle-mapped.json](../_attachments/config/routes/00-throttle-mapped.json)

## More information

[org.forgerock.openig.filter.throttling.MappedThrottlingPolicyHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/throttling/MappedThrottlingPolicyHeaplet.html)