Skip to main content

Rate-limiting for the requests library

Project description


Build status Documentation Status PyPI PyPI - Python Versions PyPI - Format

Work in progress

This package is a thin wrapper around pyrate-limiter that adds convenient integration with the requests library.


  • pyrate-limiter implements the leaky bucket algorithm, supports multiple rate limits, and an optional Redis backend
  • requests-ratelimiter can be used as a transport adapter, session, or session mixin for compatibility with other requests-based libraries.
  • Rate limits can be automatically tracked separately per host, and different rate limits can be manually applied to different hosts


pip install requests-ratelimiter



Example with LimiterSession:

from pyrate_limiter import Duration, RequestRate
from requests import Session
from requests_ratelimiter import LimiterSession

# Apply a rate-limit (5 requests per second) to all requests
session = LimiterSession(RequestRate(5, Duration.SECOND))

# Make rate-limited requests that stay within 5 requests per second
for _ in range(10):
    response = session.get('')


Example with LimiterAdapter:

from pyrate_limiter import Duration, RequestRate
from requests import Session
from requests_ratelimiter import LimiterAdapter

session = Session()

# Apply a rate-limit (5 requests per second) to all requests
adapter = LimiterAdapter(RequestRate(5, Duration.SECOND))
session.mount('http://', adapter)
session.mount('https://', adapter)

# Make rate-limited requests
for user_id in range(100):
    response = session.get(f'{user_id}')

Per-Host Rate Limits

With LimiterAdapter, you can apply different rate limits to different hosts or URLs:

# Apply different rate limits (2/second and 100/minute) to a specific host
adapter_2 = LimiterAdapter(
    RequestRate(2, Duration.SECOND),
    RequestRate(100, Duration.MINUTE),
session.mount('', adapter_2)

Behavior for matching requests is the same as other transport adapters: requests will use the adapter with the most specific (i.e., longest) URL prefix for a given request. For example:

session.mount('', adapter_3)
session.mount('', adapter_4)

# This request will use adapter_3

# This request will use adapter_4

Per-Host Rate Limit Tracking

With either LimiterSession or LimiterAdapter, you can automatically track rate limits separately for each host; in other words, requests sent to one host will not count against the rate limit for any other hosts. This can be enabled with the per_host option:

session = LimiterSession(RequestRate(5, Duration.SECOND), per_host=True)

# Make requests for two different hosts
for _ in range(10):
    response = session.get(f'')


There are many other useful libraries out there that add features to requests, most commonly by extending or modifying requests.Session.

To use requests-ratelimiter with one of these libraries, you have at least two options:

  1. Mount a LimiterAdapter on an instance of the library's Session class
  2. Use LimiterMixin to create a custom Session class with features from both libraries


For example, to combine with requests-cache, which also includes a separate mixin class:

from requests_cache import CacheMixin
from requests_ratelimiter import LimiterMixin

class CachedLimiterSession(LimiterMixin, CacheMixin, Session):
    """Session class with caching and rate-limiting behavior. Accepts arguments for both
    LimiterSession and CachedSession.

session = CachedLimiterSession(RequestRate(5, Duration.SECOND), backend='redis')

This example has an extra benefit: cache hits won't count against your rate limit!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

requests-ratelimiter-0.1.1.tar.gz (5.3 kB view hashes)

Uploaded Source

Built Distribution

requests_ratelimiter-0.1.1-py3-none-any.whl (5.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page