---
title: MappedThrottlingPolicy
description: Maps different throttling rates to different groups of requests, according to the evaluation of throttlingRateMapper.
component: pinggateway
version: 2025.3
page_id: pinggateway:reference:MappedThrottlingPolicy
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/MappedThrottlingPolicy.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/MappedThrottlingPolicy.html
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. For information about how to set up and test this example, see [Configure Mapped Throttling](../gateway-guide/throttling.html#throttling-mapped).

```json
{
  "name": "00-throttle-mapped",
  "baseURI": "http://app.example.com:8081",
  "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)