---
name: "Net::Twitter::Role::RateLimit"
section: "3pm"
platform: "linux"
package: "libnet-twitter-perl"
version: "4.01043-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Net::Twitter::Role::RateLimit"
---

# Net::Twitter::Role::RateLimit(3pm)

Rate limit features for Net::Twitter

## NAME

Net::Twitter::Role::RateLimit - Rate limit features for Net::Twitter

## VERSION

version 4.01043

## SYNOPSIS

```
    use Net::Twitter;
    my $nt = Net::Twitter->new(
        traits => [qw/API::REST RateLimit/],
        %other_options,
    );
    #...later
    sleep $nt->until_rate(1.0) || $minimum_wait;
```

## NOTE!

RateLimit only works with Twitter API v1. The rate limiting strategy of Twitter API v1.1 is very different. A v1.1 compatible RateLimit role may be coming, but isn't available, yet. It's interface will necessarily be different.

## DESCRIPTION

This provides utility methods that return information about the current rate limit status.

## METHODS

If current rate limit data is not resident, these methods will force a call to `"rate_limit_status"`.  Therefore, any of these methods can throw an error.

- rate\_remaining

  Returns the number of API calls available before the next reset.

- rate\_reset

  Returns the Unix epoch time of the next reset.

- rate\_limit

  Returns the current hourly rate limit.

- rate\_ratio

  Returns remaining API call limit, divided by the time remaining before the next reset, as a ratio of the total rate limit per hour.

  For example, if `"rate_limit"` is 150, the total rate is 150 API calls per hour. If `"rate_remaining"` is 75, and there 1800 seconds (1/2 hour) remaining before the next reset, `"rate_ratio"` returns 1.0, because there are exactly enough API calls remaining to maintain he full rate of 150 calls per hour.

  If `"rate_remaining"` is 30 and there are 360 seconds remaining before reset, `"rate_ratio"` returns 2.0, because there are enough API calls remaining to maintain twice the full rate of 150 calls per hour.

  As a final example, if `"rate_remaining"` is 15, and there are 7200 seconds remaining before reset, `"rate_ratio"` returns 0.5, because there are only enough API calls remaining to maintain half the full rate of 150 calls per hour.

- until\_rate($target\_ratio)

  Returns the number of seconds to wait before making another rate limited API call such that `$target_ratio` of the full rate would be available.  It always returns a number greater than, or equal to zero.

  Use a target rate of 1.0 in a timeline polling loop to get a steady polling rate, using all the allocated calls, and adjusted for other API calls as they occur.

  Use a target rate \< 1.0 to allow a process to make calls as fast as possible but not consume all of the calls available, too soon.  For example, if you have a process building a large social graph, you may want to allow it make as many calls as possible, with no wait, until 20% of the available rate remains.  Use a value of 0.2 for that purpose.

  A target rate \> than 1.0 can be used for a process that should only use "extra" available API calls.  This is useful for an application that requires most of it's rate limit for normal operation.

## AUTHOR

Marc Mims \<marc@questright.com\>

## LICENSE

Copyright (c) 2016 Marc Mims

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.