Key-Value

Every Stateful Actor has private, durable key/value storage at this.ctx.storage. It is the default place to keep an entity’s state: a cart’s items, a call leg’s status, a per-user counter. Reach for it first, and drop to SQL only when a lookup by key isn’t enough and you’d otherwise scan. The store is private, strongly consistent, and transactional: only this actor instance reads and writes its keys, its methods run one at a time (serialized turns), and a write that returns successfully is durable — it survives the actor being evicted, relocated, or its pod replaced. Reads always reflect your prior writes.

This is a guide. For the exact method signatures, list options, and codec rules, see the Actor Storage reference.

Reading and Writing

get and put are the whole surface for simple state. Both are async — they may cross the network — so await them:

import { StatefulActor } from "@telnyx/edge-runtime";

export class Cart extends StatefulActor {
  async add(item: string) {
    const items = (await this.ctx.storage.get<string[]>("items")) ?? [];
    items.push(item);
    await this.ctx.storage.put("items", items);
    return items.length;
  }

  async clear() {
    await this.ctx.storage.delete("items");   // returns true iff the key existed
  }
}

State is lazy per get — nothing is preloaded when the actor activates; you read a key when you need it. Values round-trip through a codec, so JSON natives plus Date, Map, Set, typed arrays, ArrayBuffer, BigInt, and RegExp come back as what you stored. Functions, class instances, promises, and circular structures are rejected at the write. Keys are strings. Those starting with __telnyx_ are reserved for the runtime — writes to them are rejected.

Listing Keys

list returns a Map in lexicographic key order, which makes prefixes a natural grouping:

// Every message in a room, in order:
const messages = await this.ctx.storage.list<Message>({ prefix: "msg:" });

// The 20 most recent, newest first:
const recent = await this.ctx.storage.list<Message>({
  prefix: "msg:",
  reverse: true,
  limit: 20,
});

limit defaults to 128 and maxes at 1000. Use start / startAfter / end to page through a large keyspace. See the reference for the full ListOptions.

Atomic Updates

transaction batches multiple keys into one atomic unit — all of the writes land, or none do:

await this.ctx.storage.transaction(async (txn) => {
  const balance = (await txn.get<number>("balance")) ?? 0;
  await txn.put("balance", balance - amount);
  await txn.put("updated_at", Date.now());
});

If the callback throws, its buffered writes are discarded. Note that a thrown transaction also fails the enclosing method call — it is not a “try the write, continue on failure” tool. See the reference for the exact semantics.

Clearing an Actor

deleteAll() atomically removes every key for this actor. It does not clear a pending alarm — delete that separately if you want the actor fully reset.

Key/Value or SQL?

Both live under this.ctx.storage, are durable and strongly consistent, and can be used together in the same actor.

Key/value (this page): simple keyed state, prefix listing, atomic multi-key updates. The default.
SQL: relational shape, aggregates, GROUP BY, secondary indexes, and joins within one actor — when a keyed lookup isn’t enough.

SQL storage — the ctx.storage.sql guide
Actor Storage reference — full method signatures and codec rules
Alarms — scheduled self-wakeups

Overview

Get Started

Concepts

Reference

Guides

For AI Agents

Reading and Writing

Listing Keys

Atomic Updates

Clearing an Actor

Key/Value or SQL?

​Reading and Writing

​Listing Keys

​Atomic Updates

​Clearing an Actor

​Key/Value or SQL?

​Related

Reading and Writing

Listing Keys

Atomic Updates

Clearing an Actor

Key/Value or SQL?

Related