KV Binding

Key-value storage for small data with low latency. Ideal for caching, sessions, feature flags, and configuration.

KV stores values as JSON natively — you can put strings, numbers, booleans, objects, and arrays directly without manual serialization.

Setup

Usage

export default {
  async fetch(request, env) {
    // Read a value
    const user = await env.KV.get('user:123');

    if (!user) {
      return new Response('Not found', { status: 404 });
    }

    return Response.json(user);
  }
};

Operations

get(key)

Read a value by key. Returns null if the key doesn’t exist or has expired.

// Returns the parsed value directly
const user = await env.KV.get('user:123');
// user is { name: 'John', role: 'admin' } — already an object

if (user === null) {
  console.log('Key not found');
}

TypeScript: Use the generic type parameter for type inference:

interface User {
  name: string;
  role: 'admin' | 'user';
}

const user = await env.KV.get<User>('user:123');
// user is User | null

put(key, value, options?)

Store a JSON-serializable value. Optionally set an expiration time.

// Store an object
await env.KV.put('user:123', { name: 'John', role: 'admin' });

// Store a string
await env.KV.put('greeting', 'Hello, World!');

// Store a number
await env.KV.put('counter', 42);

// With expiration (TTL in seconds)
await env.KV.put('session:abc', { userId: 123 }, { expiresIn: 3600 }); // Expires in 1 hour

Note: Updating a key without expiresIn removes any existing expiration.

delete(key)

Delete a key.

await env.KV.delete('session:expired');

list(options?)

List all keys in the namespace. Returns an array of key names.

// List all keys
const keys = await env.KV.list();

// With prefix filter
const userKeys = await env.KV.list({ prefix: 'user:' });

// With limit
const firstTen = await env.KV.list({ limit: 10 });

Use Cases

Session storage with expiration

export default {
  async fetch(request, env) {
    const sessionId = request.headers.get('Cookie')?.match(/session=(w+)/)?.[1];

    if (!sessionId) {
      return new Response('Unauthorized', { status: 401 });
    }

    const session = await env.KV.get(`session:${sessionId}`);

    if (!session) {
      return new Response('Session expired', { status: 401 });
    }

    // Refresh session TTL on activity
    await env.KV.put(`session:${sessionId}`, session, { expiresIn: 1800 });

    return new Response('OK');
  }
};

Feature flags

const flags = await env.KV.get('feature-flags') || {};

if (flags.newCheckout) {
  // Show new checkout flow
}

Rate limiting with auto-expiration

const ip = request.headers.get('CF-Connecting-IP');
const key = `ratelimit:${ip}`;
const count = (await env.KV.get(key)) || 0;

if (count > 100) {
  return new Response('Too many requests', { status: 429 });
}

// Auto-reset after 1 minute
await env.KV.put(key, count + 1, { expiresIn: 60 });

List and cleanup

// Find all sessions
const sessions = await env.KV.list({ prefix: 'session:' });

for (const key of sessions) {
  const data = await env.KV.get(key);

  if (shouldCleanup(data)) {
    await env.KV.delete(key);
  }
}

Limits

Supported Value Types

KV stores JSON-serializable values. The following types are supported:

Note: Binary data (Uint8Array, ArrayBuffer) is not supported. Use the Storage binding for binary data.

KV vs Storage

Use KV for small, frequently accessed JSON data with optional expiration. Use Storage for larger files or binary data.