Methods - Upstash Documentation

This page contains information on what methods are available in Ratelimit and how they can be used. For information on the cost of these operations in term of number of Redis commands, refer to the Costs page.

`limit`#

The limit method is the heart of the Ratelimit algorithm.

ratelimit.limit(  identifier: string,  req?: {    geo?: Geo;    rate?: number,    ip?: string,    userAgent?: string,    country?: string  },): Promise<RatelimitResponse>

It receives an identifier to rate limit. Additionally, it can be passed a req parameter which can contain either a geo or a rate field. geo field is passed to the analytics but is not in use currently. The rate field determines the amount of tokens/requests to subtract from the state of the algorithm with regards to the provided identifier.

The limit method returns some more metadata that might be useful to you:

export type RatelimitResponse = {  /**   * Whether the request may pass(true) or exceeded the limit(false)   */  success: boolean;  /**   * Maximum number of requests allowed within a window.   */  limit: number;  /**   * How many requests the user has left within the current window.   */  remaining: number;  /**   * Unix timestamp in milliseconds when the limits are reset.   */  reset: number;  /**   * For the MultiRegion setup we do some synchronizing in the background, after returning the current limit.   * Or when analytics is enabled, we send the analytics asynchronously after returning the limit.   * In most case you can simply ignore this.   *   * On Vercel Edge or Cloudflare workers, you need to explicitly handle the pending Promise like this:   *   * ```ts   * const { pending } = await ratelimit.limit("id")   * context.waitUntil(pending)   * ```   *   * See `waitUntil` documentation in   * [Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil)   * and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil)   * for more details.   * ```   */  pending: Promise<unknown>;  /**   * Reason behind the result in `success` field.   * - Is set to "timeout" when request times out   * - Is set to "cacheBlock" when an identifier is blocked through cache without calling redis because it was   *    rate limited previously.   * - Is set to "denyList" when identifier or one of ip/user-agent/country parameters is in deny list. To enable   *    deny list, see `enableProtection` parameter. To edit the deny list, see the Upstash Ratelimit Dashboard   *    at https://console.upstash.com/ratelimit.   * - Is set to undefined if rate limit check had to use Redis. This happens in cases when `success` field in   *    the response is true. It can also happen the first time sucecss is false.   */  reason?: RatelimitResponseType;  /**   * The value which was in the deny list if reason: "denyList"   */  deniedValue?: string;};

`blockUntilReady`#

In case you don't want to reject a request immediately but wait until it can be processed, we also provide

ratelimit.blockUntilReady(  identifier: string,  timeout: number): Promise<RatelimitResponse>

It is very similar to the limit method and takes an identifier and returns the same response. However if the current limit has already been exceeded, it will automatically wait until the next window starts and will try again. Setting the timeout parameter (in milliseconds) will cause the returned Promise to resolve in a finite amount of time.

// Create a new ratelimiter, that allows 10 requests per 10 secondsconst ratelimit = new Ratelimit({  redis: Redis.fromEnv(),  limiter: Ratelimit.slidingWindow(10, "10 s"),  analytics: true,});// `blockUntilReady` returns a promise that resolves as soon as the request is allowed to be processed, or after 30 secondsconst { success } = await ratelimit.blockUntilReady("id", 30_000);if (!success) {  return "Unable to process, even after 30 seconds";}doExpensiveCalculation();return "Here you go!";

Warning

In Cloudflare, blockUntilReady will not work as intended due to Date.now() not behaving the same as in Node environments.

For more information, check:
https://developers.cloudflare.com/workers/runtime-apis/web-standards

`resetUsedTokens`#

This method resets the state of the algorithm with respect to some identifier:

ratelimit.resetUsedTokens(identifier: string): Promise<void>

`getRemaining`#

This method returns the remaining tokens/requests available for some identifier:

ratelimit.getRemaining(identifier: string): Promise<{  remaining: number;  reset: number;}>

remaining is the remaining tokens. reset is the reset timestamp.

`setDynamicLimit`#

This method sets or removes a global dynamic rate limit. Dynamic limits override the default limiter settings for all subsequent rate limit checks.

ratelimit.setDynamicLimit(options: {  limit: number | false;}): Promise<void>

Parameters:

limit: The new limit value (number), or false to remove the dynamic limit and fall back to the default

Example:

const ratelimit = new Ratelimit({  redis: Redis.fromEnv(),  limiter: Ratelimit.slidingWindow(10, "10s"),  dynamicLimits: true,});// Set a new dynamic limitawait ratelimit.setDynamicLimit({ limit: 5 });// Remove dynamic limit (falls back to default of 10)await ratelimit.setDynamicLimit({ limit: false });

`getDynamicLimit`#

This method retrieves the current dynamic limit if one is set.

ratelimit.getDynamicLimit(): Promise<{ dynamicLimit: number | null }>

Returns: The current dynamic limit value, or null if no dynamic limit is set

Example:

const ratelimit = new Ratelimit({  redis: Redis.fromEnv(),  limiter: Ratelimit.slidingWindow(10, "10s"),  dynamicLimits: true,});await ratelimit.setDynamicLimit({ limit: 5 });const { dynamicLimit } = await ratelimit.getDynamicLimit(); // returns 5

limit#

blockUntilReady#

resetUsedTokens#

getRemaining#

setDynamicLimit#

getDynamicLimit#

`limit`#

`blockUntilReady`#

`resetUsedTokens`#

`getRemaining`#

`setDynamicLimit`#

`getDynamicLimit`#