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

# Quickstart

Get up and running with Choked in minutes.

## Installation

```bash theme={null}
pip install choked
```

## Basic Usage

Create a Choked instance and use it as a decorator:

```python theme={null}
from choked import Choked

# Create instance with Redis backend
choke = Choked(redis_url="redis://localhost:6379/0")

@choke(key="my_function", request_limit="5/10s")
def my_rate_limited_function():
    print("This function can be called 5 times every 10 seconds")
    return "success"

# Call the function
result = my_rate_limited_function()
```

## Backend Options

Choose between Redis (self-hosted) or managed proxy service:

### Redis Backend

```python theme={null}
from choked import Choked

choke = Choked(redis_url="redis://localhost:6379/0")
```

### Managed Proxy Service

```python theme={null}
from choked import Choked

choke = Choked(api_token="your-api-token")
```

## Parameters Explained

* **`key`**: Unique identifier for this rate limit. Functions with the same key share the same bucket.
* **`request_limit`**: Request rate limit (e.g., "10/s", "100/m"). Optional if token\_limit provided.
* **`token_limit`**: Token rate limit (e.g., "1000/s", "100000/m"). Optional if request\_limit provided.
* **`token_estimator`**: Token estimation method ("openai", "voyageai", "default"). Required for token\_limit.

## Async Functions

Choked automatically detects and handles async functions:

```python theme={null}
import asyncio
from choked import Choked

choke = Choked(redis_url="redis://localhost:6379/0")

@choke(key="async_api", request_limit="3/5s")
async def async_api_call():
    print("Async function with rate limiting")
    return "async result"

# Use with asyncio
async def main():
    result = await async_api_call()
    print(result)

asyncio.run(main())
```

## Token-Based Limiting

Perfect for AI/ML APIs that have token limits:

```python theme={null}
from choked import Choked

choke = Choked(api_token="your-token")

@choke(key="openai_chat", token_limit="100000/m", token_estimator="openai")
def chat_completion(messages):
    # Automatically estimates tokens from messages
    return openai.chat.completions.create(
        model="gpt-4",
        messages=messages
    )
```

## Dual Limiting

Apply both request and token limits simultaneously:

```python theme={null}
@choke(key="api_dual", request_limit="50/s", token_limit="100000/m", token_estimator="openai")
def dual_limited_function(text):
    # Limited by both requests (50/s) AND tokens (100K/m)
    return process_text(text)
```

## Multiple Rate Limits

You can create multiple Choked instances or use different keys:

```python theme={null}
# Different instances for different services
openai_choke = Choked(api_token="openai-token")
voyage_choke = Choked(api_token="voyage-token")

@openai_choke(key="gpt4", request_limit="50/s", token_limit="100000/m", token_estimator="openai")
def gpt4_call(messages):
    return "GPT-4 response"

@voyage_choke(key="embed", token_limit="1000000/m", token_estimator="voyageai")
def voyage_embed(texts):
    return "Embeddings"
```

## Next Steps

* Learn about [Configuration](essentials/configuration) options
* Understand [Token Buckets](essentials/token-buckets) in detail