Skip to main content

API Rate Limit

Manage quotas and limit to your APIs.


The API rate limit object defines the consumption limit for consumers of APIs.

The limits are attached to groups and applied to APIs or Collections.

Good to know
  • You can configure multiple rate limits, using any combination of groups and APIs.
  • An API can have multiple rate limit policies.
  • When an API, for the same group, has two rate limits applied, the least privileged prevails (allowing restrictions on selected APIs).
  • When a user has access to the same API through different groups, the most privileged group prevails for that user / API.

Rate Limiting Behavior

Limits over Time

Rate limit diagram

Traefik Hub uses the Token Bucket algorithm.

The token bucket algorithm defines the number of requests that can be served in a given period of time.

With a 1m period and a limit of 10 requests, Traefik Hub accepts an average of 0.16 request per second (10/60s).
In other words, every 0.16 seconds, the bucket receives a new token.

This represents the rate at which the bucket of available requests fills up.

Users spend one token for each request that gets removed from the bucket. Simultaneously, the bucket is refilled at a constant rate, given that it isn't already full.

If users spend tokens faster than buckets are refilled, requests will be rejected once the bucket is empty and until new tokens are available.


101mThe bucket gets a new token every .16 seconds (10 / 60 seconds).
1001hThe bucket gets a new token every .02 seconds (100 / 3600 seconds).

Multiple Rate Limits

Same Group, Same API

Within the same group, if two rate limits target the same API, the least favorable one applies.
This allows API Managers to declare a general rule for consumption, then apply exceptions for a subset of APIs.

Group NameAPI NameRate limit
Group AAPI A5rq/s
Group AAPI A, B, C10rq/s

If a user belongs to Group A, they will get 5rq/s on API A, which is the least favorable one on API A, but will get 10rq/s on API B and C.

Different Groups, Same API

When different groups provide access to the same API, the most favorable one applies.

Group NameAPI NameRate limit
Group A5API A5rq/s
Group A10API A10rq/s

If a user belongs to Group A5 and Group A10, they will get 10rq/s on API A, which is the most favorable one from their groups.

Combining Groups and APIs

The priority rules described above apply.

Group NameAPI NameRate limit
Group AAPI A8rq/s
Group AAPI A, B10rq/s
Group BAPI A, API C5rq/s

If a user belongs to group A and group B, they will get:

  • 8rq/s on API A (5 from Group B, and 8 from group A. The most favorable group applies, but within the group the least favorable applies)
  • 10rq/s on API B (from Group B)
  • 5rq/s on API C (from Group B)

Local & Distributed Rate Limiting

Traefik Hub supports two strategies: local and distributed rate limiting.

Local rate limiting applies rate limiting policies to a single Traefik Hub agent.
If you scale an API using two Traefik Hub agents, each agent will use its own bucket (spending / refilling tokens).

Distributed rate limiting shares the bucket among multiple Traefik Hub agents.
If you scale an API using two Traefik Hub agents, one policy and thus one bucket configuration will be used across all Traefik Hub agents.


Local is the default strategy for rate limiting because it doesn't require extra configuration.

When configuring a distributed rate limiting strategy, Traefik Hub requires that you configure a Redis as a storage location.

Rate Limiting Configuration Options

limitThe number of tokens in a bucket.Yes
periodThe time period (speed) at which the tokens are added into the bucket. Time period can be seconds, minutes or hours (s/m/h). Default value is one second.second.No
anyGroupsanyGroups will apply to every group and any user, whether they belong to a group or not.No
groupsName of the group(s) which will be rate limited. See the user management reference for more information.No
apis.nameSelect APIs based on names. You can combine it with apiSelector.matchLabels and apiSelector.matchExpressions. See Labels and Selectors.No
apis.namespaceName of the Kubernetes Namespace used by the API(s) defined in This is required for
apiSelector.matchLabelsSelect APIs based on label matching: Equality-Based Requirements.No
apiSelector.matchExpressionsSelect APIs based on advanced labels expressions: Set-Based Requirements.No

You must configure either anyGroups or groups for rate limiting.
Without setting one of them, rate limiting will not be applied.

Managing API Rate Limiting Using CRDs

Using the Local strategy (default)
kind: APIRateLimit
name: my-rate-limit

# Rate limit configuration, this config allows 100 requests/minute.
limit: 100 # 100 requests
period: 1m # One minute

- support

module: crm