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

# Use KV Store

> KVStore is a simple key-value storage for sharing state across serverless runners with zero setup required.

KVStore provides a way to share small string values across all your serverless runners. It supports two operations: `get` and `set`. Use it for caching computation results, sharing configuration between runners, or storing small pieces of state that multiple runners need to read. It requires no setup and uses automatic authentication with your fal credentials.

Unlike [persistent storage](/documentation/development/use-persistent-storage) on `/data` (a distributed filesystem for large files like model weights), KVStore is a remote key-value API accessed over HTTP. It is best suited for small, frequently-read values where you need cross-runner consistency. It does not support deletion, expiration, listing keys, or atomic operations, so it is not appropriate for counters, locks, or anything requiring transactional guarantees.

## API Reference

### Initialize KVStore

```python theme={null}
from fal.toolkit.kv import KVStore

kv = KVStore("myapp")  # "myapp" is your namespace
```

Each namespace is isolated - different `db_name` values create separate key-value stores.

### Methods

**`get(key: str) -> Optional[str]`**

Retrieve a value from the store. Returns `None` if the key doesn't exist.

```python theme={null}
value = kv.get("my-key")
if value is None:
    print("Key not found")
```

**`set(key: str, value: str) -> None`**

Store a string value. The value must be a string - use `json.dumps()` for objects.

```python theme={null}
import json

# Store a string
kv.set("my-key", "my-value")

# Store an object as JSON
kv.set("config", json.dumps({"enabled": True, "limit": 100}))
```

## Basic Example

```python theme={null}
import fal
import json
from fal.toolkit.kv import KVStore

class MyApp(fal.App):
    def setup(self):
        self.kv = KVStore("myapp")
    
    @fal.endpoint("/")
    def process(self, input: Input):
        # Check cache
        cache_key = f"result-{input.id}"
        cached = self.kv.get(cache_key)
        
        if cached:
            return json.loads(cached)
        
        # Compute and cache result
        result = self.expensive_operation(input)
        self.kv.set(cache_key, json.dumps(result))
        
        return result
```

## Common Use Cases

### Caching API Responses

Cache external API calls to reduce latency and costs:

```python theme={null}
class MyApp(fal.App):
    def setup(self):
        self.kv = KVStore("api-cache")
    
    @fal.endpoint("/")
    def process(self, input: Input):
        cache_key = f"weather:{input.city}"
        
        # Check cache
        cached = self.kv.get(cache_key)
        if cached:
            return json.loads(cached)
        
        # Fetch from external API
        weather = requests.get(f"https://api.weather.com/{input.city}").json()
        self.kv.set(cache_key, json.dumps(weather))
        
        return weather
```

### Caching Computation Results

Store results of expensive operations to avoid recomputation:

```python theme={null}
class MyApp(fal.App):
    def setup(self):
        self.kv = KVStore("compute-cache")
    
    @fal.endpoint("/")
    def process(self, input: Input):
        cache_key = f"result:{input.video_id}"
        
        cached = self.kv.get(cache_key)
        if cached:
            return json.loads(cached)
        
        # Expensive video processing
        result = self.process_video(input.video_url)
        self.kv.set(cache_key, json.dumps(result))
        
        return result
```

## Limitations

KVStore is deliberately simple. It only supports `get` and `set` on string values. There is no `delete`, no key listing/scanning, no TTL or expiration, and no atomic operations (no increment, no compare-and-swap). Values persist indefinitely until overwritten.

If multiple runners write to the same key simultaneously, the last write wins with no conflict detection. This makes KVStore unsuitable for counters, locks, rate limiting, or anything requiring atomicity. For those use cases, use an external database like Redis or PostgreSQL.

For large files (model weights, datasets), use the [`/data` volume](/documentation/development/use-persistent-storage) instead.