Limit Count | APISIX & API7 API Gateway Docs

Parameters

See plugin common configurations for configuration options available to all plugins.

This plugin supports referencing parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin and secrets.

count
integer | string
required
vaild vaule:
greater than 0
The maximum number of requests allowed within a given time interval.
In API7 Enterprise (from 3.8.17) and in APISIX (from 3.16.0), this parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($). In earlier APISIX versions, only the integer type is supported.
time_window
integer | string
required
vaild vaule:
greater than 0
The time interval corresponding to the rate limiting count in seconds.
In API7 Enterprise (from 3.8.17) and in APISIX (from 3.16.0), this parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($). In earlier APISIX versions, only the integer type is supported.
key_type
string
default: var
vaild vaule:
var, var_combination, or constant
The type of key.
If the key_type is var, the key is interpreted as a variable.
If the key_type is var_combination, the key is interpreted as a combination of variables.
If the key_type is constant, the key is interpreted as a constant.
key
string
default: remote_addr
The key to count requests by.
If the key_type is var, the key is interpreted as a variable. The variable does not need to be prefixed by a dollar sign ($). See built-in variables for available variables.
If the key_type is var_combination, the key is interpreted as a combination of variables. All variables should be prefixed by dollar signs ($). For example, to configure the key to use a combination of two request headers custom-a and custom-b, the key should be configured as $http_custom_a $http_custom_b.
If the key_type is constant, the key is interpreted as a constant value.
rejected_code
integer
default: 503
vaild vaule:
between 200 and 599 inclusive
The HTTP status code returned when a request is rejected for exceeding the threshold.
rejected_msg
string
vaild vaule:
any non-empty string
The response body returned when a request is rejected for exceeding the threshold.
policy
string
default: local
vaild vaule:
local, redis, or redis-cluster
The policy for rate limiting counter. Required for API7 Enterprise and optional for APISIX.
When set to local, the counter is stored in memory locally. When set to redis, the counter is stored on a Redis instance. When set to redis-cluster, the counter is stored in a Redis cluster.
allow_degradation
boolean
default: false
If true, allow APISIX to continue handling requests without the plugin when the plugin or its dependencies become unavailable.
show_limit_quota_header
boolean
default: true
If true, includes the rate limiting response headers. Specifically:
- X-RateLimit-Limit shows the total quota.
- X-RateLimit-Remaining shows the remaining quota.
- X-RateLimit-Reset shows the number of seconds until the counter resets.
group
string
vaild vaule:
non-empty
The group ID for the plugin, such that routes of the same group can share the same rate limiting counter.
redis_host
string
The address of the Redis node. Required when policy is redis.
redis_port
integer
default: 6379
vaild vaule:
greater than or equal to 1
The port of the Redis node when policy is redis.
redis_username
string
The username for Redis if Redis ACL is used. If you use the legacy authentication method requirepass, configure only the redis_password. Used when policy is redis.
redis_password
string
The password of the Redis node when policy is redis or redis-cluster.
redis_database
integer
default: 0
vaild vaule:
greater than or equal to 0
The database number in Redis when policy is redis.
redis_ssl
boolean
default: false
If true, use SSL to connect to Redis when policy is redis.
redis_ssl_verify
boolean
default: false
If true, verify the server SSL certificate when policy is redis.
redis_timeout
integer
default: 1000
vaild vaule:
greater than or equal to 1
The Redis timeout value in milliseconds when policy is redis or redis-cluster.
redis_keepalive_timeout
integer
default: 10000
vaild vaule:
greater than or equal to 1000
Keepalive timeout in milliseconds for Redis when policy is redis or redis-cluster.
This parameter is available in APISIX from version 3.15.0 and is not yet available in API7 Enterprise.
redis_keepalive_pool
integer
default: 100
vaild vaule:
greater than or equal to 1
Keepalive pool size for Redis when policy is redis or redis-cluster.
This parameter is available in APISIX from version 3.15.0 and is not yet available in API7 Enterprise.
redis_cluster_nodes
array[string]
The list of Redis cluster nodes with at least one address. Required when policy is redis-cluster.
redis_cluster_name
string
The name of the Redis cluster. Required when policy is redis-cluster.
redis_cluster_ssl
boolean
default: false
If true, use SSL to connect to Redis cluster when policy is redis-cluster.
redis_cluster_ssl_verify
boolean
default: false
If true, verify the server SSL certificate when policy is redis-cluster.
rules
array[object]
An array of rate-limiting rules that are applied sequentially. When configured, the top-level count, time_window, and key fields are ignored.
Available in API7 Enterprise from 3.8.17 and in APISIX from 3.16.0.
- count
  integer | string
  required
  vaild vaule:
  greater than 0
  The maximum number of requests allowed within the given time_window.
  This parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).
- time_window
  integer | string
  required
  vaild vaule:
  greater than 0
  The time interval in seconds for the rate limiting count.
  This parameter also supports the string data type and allows the use of built-in variables prefixed with a dollar sign ($).
- key
  string
  required
  The key to count requests by. Supports APISIX built-in variables and NGINX variables.
  If the key_type is var, the variable does not need to be prefixed by a dollar sign ($).
  If the key_type is var_combination, all variables should be prefixed by dollar signs ($).
- header_prefix
  string
  A prefix inserted after X-RateLimit- in the rate limiting response headers for this rule (e.g. foo produces X-RateLimit-foo-Limit, X-RateLimit-foo-Remaining, X-RateLimit-foo-Reset). Only used when show_limit_quota_header is true.

Plugin Metadata

limit_header
string
default: X-RateLimit-Limit
Default response header name for the total rate limit quota.
remaining_header
string
default: X-RateLimit-Remaining
Default response header name for the remaining rate limit quota.
reset_header
string
default: X-RateLimit-Reset
Default response header name for the number of seconds until the rate limit counter resets.

Parameters​

Plugin Metadata​

Parameters

Plugin Metadata