Search docs ⌘K
esc
Type to search across all documentation pages
KV

KV Store

A global key-value store backed by Cloudflare KV. Sub-millisecond reads from 300+ edge locations. Keys are namespaced per project — no collisions between projects.

Eventual consistency: CF KV propagates writes globally within ~60 seconds. For strong read-after-write within the same edge PoP (e.g., right after setting a session), use the cache: 'no-store' option or rely on the response body returned from PUT.

Get Value

GET
json — 200 OK
{
  "key": "session:u_123",
  "value": { "userId": "u_123", "role": "admin" },
  "expires_at": "2026-03-05T00:00:00Z"
}
typescript
const entry = await ss.infra.kv.get('session:u_123')
// entry.value, entry.expires_at
  1. Open Dashboard and select your project
  2. Go to KV Store in the sidebar
  3. Search or browse keys, then click any key to view its value and metadata
Path param
Type
Description
key required
string
Key to retrieve (1–512 chars, no control characters or .. sequences)

Set Value

GET
json — 200 OK
{ "key": "session:u_123", "value": { ... }, "expires_at": "2026-03-05T..." }
typescript
await ss.infra.kv.set('session:u_123', { userId: 'u_123', role: 'admin' }, { ttl: 86400 })
  1. Open Dashboard and select your project
  2. Go to KV Store → click Add Key
  3. Enter the key name, paste your JSON value, optionally set a TTL
  4. Click Save
Path param
Type
Description
key required
string
Key to store (1–512 chars, no control characters or .. sequences)
Body field
Type
Description
value required
any JSON
Value to store (max 256 KB serialized)
ttl
integer
Time-to-live in seconds. Key expires after this duration.
if_not_exists
boolean
If true, fail with 409 when the key already exists. Default false.

Delete Key

GET
typescript
await ss.infra.kv.delete('session:u_123')
  1. Open Dashboard and select your project
  2. Go to KV Store and find the key
  3. Click the key, then click Delete
Path param
Type
Description
key required
string
Key to delete (1–512 chars, no control characters or .. sequences)

Increment Value

GET
typescript
// Rate limit: max 100 req/min
const { value } = await ss.infra.kv.increment(`ratelimit:${userId}`, { ttl: 60 })
if (value > 100) return new Response('Rate limited', { status: 429 })
  1. Increment is an API-only operation
  2. Use the REST API or TypeScript SDK to increment values
You can view the resulting value in Dashboard → KV Store
Path param
Type
Description
key required
string
Key to increment (1–512 chars, no control characters or .. sequences)
Body field
Type
Description
delta
number
Amount to increment (or decrement if negative). Default 1.
ttl
integer
Time-to-live in seconds. Applied when the key is first created.

Scan Keys

GET

Scan keys by prefix. Returns paginated key names (not values). Costs 5 μt per call.

typescript
const result = await ss.infra.kv.scan({ prefix: 'session:', limit: 50 })
// result.keys, result.next_cursor
  1. Open Dashboard and select your project
  2. Go to KV Store
  3. Use the search bar to filter keys by prefix
Query param
Type
Description
prefix
string
Key prefix to filter by (max 512 chars). Default returns all keys.
cursor
string
Pagination cursor from a previous next_cursor response.
limit
integer
Max keys to return per page. Range 1–1000, default 100.

Batch Operations

GET

Execute up to 100 get/set/delete operations in a single request. Each op is charged individually.

json — 200 OK
{
  "results": [
    { "key": "config:flags", "value": { "dark_mode": true }, "status": "ok" },
    { "key": "session:new", "value": { "userId": "u_456" }, "status": "ok" },
    { "key": "session:old", "value": null, "status": "ok" }
  ]
}
typescript
const results = await ss.infra.kv.batch([
  { op: 'get', key: 'config:flags' },
  { op: 'set', key: 'session:new', value: { userId: 'u_456' }, ttl: 3600 },
  { op: 'delete', key: 'session:old' },
])
  1. Batch operations are an API-only feature
  2. Use the REST API or TypeScript SDK for bulk operations
You can manage keys individually in Dashboard → KV Store
Body field
Type
Description
ops required
array
Array of operations (max 100). Each op: { op: "get"|"set"|"delete", key, value?, ttl? }. value is required for set.