---
title: ScriptableThrottlingPolicy
description: Uses a script to look up the throttling rates to apply to groups of requests.
component: pinggateway
version: 2026
page_id: pinggateway:reference:ScriptableThrottlingPolicy
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/ScriptableThrottlingPolicy.html
revdate: 2025-10-15T18:45:22Z
section_ids:
  ScriptableThrottlingPolicy-usage: Usage
  ScriptableThrottlingPolicy-properties: Properties
  example-throttling-scriptable: Example of a scriptable throttling policy
  ScriptableThrottlingPolicy-moreinfo: More information
---

# ScriptableThrottlingPolicy

Uses a script to look up the throttling rates to apply to groups of requests.

The script can store the mapping for the throttling rate in memory, and can use a more complex mapping mechanism than that used in the `MappedThrottlingPolicy`. For example, the script can map the throttling rate for a range of IP addresses. The script can also query an external database or read the mapping from a file.

Scripts must return a [Promise\<ThrottlingRate, Exception>](../_attachments/apidocs/org/forgerock/util/promise/Promise.html) or a [ThrottlingRate](../_attachments/apidocs/org/forgerock/openig/filter/throttling/ThrottlingRate.html).

For information about script properties, available global objects, and automatically imported classes, refer to [PingGateway scripts](Scripts.html).

* For an example of how to create a ScriptableThrottlingPolicy in Studio, refer to [Configure scriptable throttling](../gateway-guide/throttling.html#throttling-scriptable).

## Usage

```json
{
  "type": "ThrottlingFilter",
  "config": {
    "requestGroupingPolicy": runtime expression<string>,
    "throttlingRatePolicy": {
      "name": string,
      "type": "ScriptableThrottlingPolicy",
      "config": {
        "type": configuration expression<string>,
        "file": configuration expression<string>, // Use either "file"
        "source": [ string, ... ],                // or "source", but not both
        "args": map,
        "clientHandler": Handler reference
        }
    }
  }
}
```

## Properties

For information about properties for ScriptableThrottlingPolicy, refer to [PingGateway scripts](Scripts.html).

## Example of a scriptable throttling policy

In the following example, the `DefaultRateThrottlingPolicy` delegates the management of throttling to the scriptable throttling policy.

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

```json
{
  "name": "00-throttle-scriptable",
  "baseURI": "https://app.example.com:8444",
  "condition": "${find(request.uri.path, '^/home/throttle-scriptable')}",
  "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": {
              "type": "DefaultRateThrottlingPolicy",
              "config": {
                "delegateThrottlingRatePolicy": {
                  "name": "ScriptedPolicy",
                  "type": "ScriptableThrottlingPolicy",
                  "config": {
                    "type": "application/x-groovy",
                    "source": [
                      "if (contexts.oauth2.accessToken.info.status == status) {",
                      "  return new ThrottlingRate(rate, duration)",
                      "} else {",
                      "  return null",
                      "}"
                    ],
                    "args": {
                      "status": "gold",
                      "rate": 6,
                      "duration": "10 seconds"
                    }
                  }
                },
                "defaultRate": {
                  "numberOfRequests": 1,
                  "duration": "10 s"
                }
              }
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}
```

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

## More information

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