> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Bucket

> Start full. Spend tokens. They come back.

The bucket holds `limit` tokens. Each allowed request spends one. Tokens refill at `limit / duration` — so a limit of 10 per 60 seconds refills one token every 6 seconds.

The bucket never goes above `limit`.

## When to use it

APIs that should tolerate a burst, then settle. A user who was idle can dump `limit` requests immediately. After that, they wait for refill.

## Burst

On first use, the bucket is full. That's the burst. If you don't want that, use [leaky bucket](/algorithms/leaky-bucket).

## Shape

<ResponseField name="remaining" type="number">
  Whole tokens left after this request.
</ResponseField>

<ResponseField name="reset_time" type="number">
  When the bucket will be full again — not when the next single token arrives.
</ResponseField>